vhad/octoprint-open-api
1
0
Fork 0
mirror of https://github.com/gosticks/octoprint-open-api.git synced 2025-10-16 11:45:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

WIP: update file api

Browse Source
This commit is contained in:
Wlad 2020-10-23 22:38:51 +02:00
parent 1fb0a42941
commit b0d49a872c
14 changed files with 146 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
openapi/components/parameters/fileLocation.yaml Normal file
View File

@ -0,0 +1,9 @@
in: path
name: location
description: >-
Retrieve information regarding the files currently available on the selected location and – if targeting the local location – regarding the disk space still available locally in the system.
schema:
type: string
enum:
- local
- sdcard

7
openapi/components/parameters/filePath.yaml Normal file
View File

@ -0,0 +1,7 @@
in: path
name: path
description: >-
The filename of the file for which to retrieve the information
schema:
type: string
format: uri

6
openapi/components/parameters/fileRecursive.yaml Normal file
View File

@ -0,0 +1,6 @@
in: query
name: recursive
description: If set to true, return all files and folders recursively. Otherwise only return items on same level.
required: false
schema:
type: boolean

35
openapi/components/requestBodies/File.yaml Normal file
View File

@ -0,0 +1,35 @@
content:
multipart/form-data:
schema:
type: object
properties:
file:
description: The file to upload, including a valid
type: string
format: binary
path:
description: >-
The path within the location to upload the file to or create the folder in (without the future filename or foldername - basically the parent folder). If unset will be taken from the provided file’s name or foldername and default to the root folder of the location.
type: string
format: uri
select:
type: boolean
description: >-
Whether to select the file directly after upload (true) or not (false). Optional, defaults to false. Ignored when creating a folder.
print:
type: boolean
description: >-
Whether to start printing the file directly after upload (true) or not (false). If set, select is implicitly true as well. Optional, defaults to false. Ignored when creating a folder.
userdata:
type: string
description: >-
An optional string that if specified will be interpreted as JSON and then saved along with the file as metadata (metadata key userdata). Ignored when creating a folder.
foldername:
type: string
description: >-
The name of the folder to create. Ignored when uploading a file.

17
openapi/components/responses/FileUpload.yaml Normal file
View File

@ -0,0 +1,17 @@
"201":
description: Created
"400":
description: >-
If no file or foldername are included in the request, userdata was provided but could not be parsed as JSON or the request is otherwise invalid.
"404":
description: >-
If location is neither local nor sdcard or trying to upload to SD card and SD card support is disabled
"409":
description: >-
If the upload of the file would override the file that is currently being printed or if an upload to SD card was requested and the printer is either not operational or currently busy with a print job.
"415":
description: >-
If the file is neither a gcode nor an stl file (or it is an stl file but slicing support is disabled)
"500":
description: >-
If the upload failed internally

15
openapi/openapi.yaml
View File

@ -21,13 +21,16 @@ paths:
$ref: paths/connection.yaml
/printer:
$ref: paths/printer.yaml
/files/local:
$ref: paths/files/local-post.yaml
/files/sdcard:
$ref: paths/files/sdcard-post.yaml
/files/{location}:
$ref: paths/files/{location}-get.yaml
get:
$ref: paths/files/{location}/get.yaml
post:
$ref: ./paths/files/{location}/post.yaml
"/files/{location}/{path}":
get:
$ref: ./paths/files/{location}/{path}-get.yaml
/files:
$ref: paths/files/get.yaml
get:
$ref: paths/files/get.yaml
/printer/tool:
$ref: paths/printer@tool.yaml

39
openapi/paths/files/get.yaml
View File

@ -1,20 +1,19 @@
get:
summary: Retrieve all files
operationId: getAllFiles
description: >-
Retrieve information regarding all files currently available and regarding the disk space still available locally in the system.
By default only returns the files and folders in the root directory. If the query parameter `recursive` is provided and set to `true`, returns all files and folders.
parameters:
- in: query
name: recursive
description: If set to true, return all files and folders recursively. Otherwise only return items on same level.
required: false
schema:
type: string
responses:
"200":
description: Returns a Retrieve response
content:
application/json:
schema:
$ref: ../../components/schemas/files/RetrieveResponse.yaml
summary: Retrieve all files
operationId: getAllFiles
description: >-
Retrieve information regarding all files currently available and regarding the disk space still available locally in the system.
By default only returns the files and folders in the root directory. If the query parameter `recursive` is provided and set to `true`, returns all files and folders.
parameters:
- in: query
name: recursive
description: If set to true, return all files and folders recursively. Otherwise only return items on same level.
required: false
schema:
type: string
responses:
"200":
description: Returns a Retrieve response
content:
application/json:
schema:
$ref: ../../components/schemas/files/RetrieveResponse.yaml

58
openapi/paths/files/local-post.yaml
View File

@ -1,58 +0,0 @@
post:
summary: Upload file or create folder
operationId: uploadToLocal
description: Upload a file to the selected location or create a new empty folder on it.
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
description: The file to upload, including a valid
type: string
format: binary
path:
description: >-
The path within the location to upload the file to or create the folder in (without the future filename or foldername - basically the parent folder). If unset will be taken from the provided file’s name or foldername and default to the root folder of the location.
type: string
format: uri
select:
type: boolean
description: >-
Whether to select the file directly after upload (true) or not (false). Optional, defaults to false. Ignored when creating a folder.
print:
type: boolean
description: >-
Whether to start printing the file directly after upload (true) or not (false). If set, select is implicitly true as well. Optional, defaults to false. Ignored when creating a folder.
userdata:
type: string
description: >-
An optional string that if specified will be interpreted as JSON and then saved along with the file as metadata (metadata key userdata). Ignored when creating a folder.
foldername:
type: string
description: >-
The name of the folder to create. Ignored when uploading a file.
responses:
"201":
description: Created
"400":
description: >-
If no file or foldername are included in the request, userdata was provided but could not be parsed as JSON or the request is otherwise invalid.
"404":
description: >-
If location is neither local nor sdcard or trying to upload to SD card and SD card support is disabled
"409":
description: >-
If the upload of the file would override the file that is currently being printed or if an upload to SD card was requested and the printer is either not operational or currently busy with a print job.
"415":
description: >-
If the file is neither a gcode nor an stl file (or it is an stl file but slicing support is disabled)
"500":
description: >-
If the upload failed internally

58
openapi/paths/files/sdcard-post.yaml
View File

@ -1,58 +0,0 @@
post:
summary: Upload file or create folder
operationId: uploadToSdCard
description: Upload a file to the selected location or create a new empty folder on it.
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
description: The file to upload, including a valid
type: string
format: binary
path:
description: >-
The path within the location to upload the file to or create the folder in (without the future filename or foldername - basically the parent folder). If unset will be taken from the provided file’s name or foldername and default to the root folder of the location.
type: string
format: uri
select:
type: boolean
description: >-
Whether to select the file directly after upload (true) or not (false). Optional, defaults to false. Ignored when creating a folder.
print:
type: boolean
description: >-
Whether to start printing the file directly after upload (true) or not (false). If set, select is implicitly true as well. Optional, defaults to false. Ignored when creating a folder.
userdata:
type: string
description: >-
An optional string that if specified will be interpreted as JSON and then saved along with the file as metadata (metadata key userdata). Ignored when creating a folder.
foldername:
type: string
description: >-
The name of the folder to create. Ignored when uploading a file.
responses:
"201":
description: Created
"400":
description: >-
If no file or foldername are included in the request, userdata was provided but could not be parsed as JSON or the request is otherwise invalid.
"404":
description: >-
If location is neither local nor sdcard or trying to upload to SD card and SD card support is disabled
"409":
description: >-
If the upload of the file would override the file that is currently being printed or if an upload to SD card was requested and the printer is either not operational or currently busy with a print job.
"415":
description: >-
If the file is neither a gcode nor an stl file (or it is an stl file but slicing support is disabled)
"500":
description: >-
If the upload failed internally

30
openapi/paths/files/{location}-get.yaml
View File

@ -1,30 +0,0 @@
get:
summary: Retrieve files from specific location
operationId: getAllFilesInLocation
description: >-
Retrieve information regarding all files currently available and regarding the disk space still available locally in the system.
By default only returns the files and folders in the root directory. If the query parameter `recursive` is provided and set to `true`, returns all files and folders.
parameters:
- in: path
name: location
required: false
description: >-
Retrieve information regarding the files currently available on the selected location and – if targeting the local location – regarding the disk space still available locally in the system.
schema:
type: string
enum:
- local
- sdcard
- in: query
name: recursive
description: If set to true, return all files and folders recursively. Otherwise only return items on same level.
required: false
schema:
type: string
responses:
"200":
description: Returns a Retrieve Response
content:
application/json:
schema:
$ref: ../../components/schemas/files/RetrieveResponse.yaml

15
openapi/paths/files/{location}/get.yaml Normal file
View File

@ -0,0 +1,15 @@
summary: Retrieve files from specific location
operationId: getAllFilesInLocation
description: >-
Retrieve information regarding all files currently available and regarding the disk space still available locally in the system.
By default only returns the files and folders in the root directory. If the query parameter `recursive` is provided and set to `true`, returns all files and folders.
parameters:
- $ref: ../../../components/parameters/fileLocation.yaml
- $ref: ../../../components/parameters/fileRecursive.yaml
responses:
"200":
description: Returns a Retrieve Response
content:
application/json:
schema:
$ref: ../../../components/schemas/files/RetrieveResponse.yaml

9
openapi/paths/files/{location}/post.yaml Normal file
View File

@ -0,0 +1,9 @@
summary: Upload file or create folder
operationId: uploadFile
description: Upload a file to the selected location or create a new empty folder on it.
parameters:
- $ref: ../../../components/parameters/fileLocation.yaml
requestBody:
$ref: ../../../components/requestBodies/File.yaml
responses:
$ref: ../../../components/responses/FileUpload.yaml

6
openapi/paths/files/{location}/{path}-delete.yaml Normal file
View File

@ -0,0 +1,6 @@
summary: Delete a file or folder
operationId: deleteFileOrFolder
description: Delete the selected path on the selected location.
parameters:
- $ref: ../../../components/parameters/fileLocation.yaml
- $ref: ../../../components/parameters/filePath.yaml

14
openapi/paths/files/{location}/{path}-get.yaml Normal file
View File

@ -0,0 +1,14 @@
summary: Retrieve a specific file’s or folder’s information
operationId: getFileOrFolder
description: Retrieves the selected file’s or folder’s information.
parameters:
- $ref: ../../../components/parameters/fileLocation.yaml
- $ref: ../../../components/parameters/filePath.yaml
- $ref: ../../../components/parameters/fileRecursive.yaml
responses:
"200":
description: Returns a Retrieve Response
content:
application/json:
schema:
$ref: ../../../components/schemas/files/RetrieveResponse.yaml