update docs structure

openapi/components/schemas/files/RetrieveResponse.yaml

@@ -8,3 +8,4 @@ properties:
     description: >-
       Remaining free space
     type: string
+    example: "25.4G"

openapi/openapi.yaml

@@ -11,29 +11,60 @@ servers:
 tags:
   - name: General
     description: General operations
-  - name: user
+  - name: User
     description: User operations
   - name: Groups
     description: User group management
-  - name: permissions
+  - name: Permissions
-  - name: system
+    description: >-
+      Retrieve system permission settings
+  - name: System
     description: OctoPrint system operations
+  - name: Settings
+    description: System settings
+  - name: System Commands
+    description: Manage and execute system commands
+
+  - name: Languages
+    description: Printer language configuration
+
+  - name: Printer
+    description: Printer operations
+  - name: Job
+    description: Control and monitor ongoing printer jobs
   - name: file
     description: File operations
-  - name: printer
+
-    description: Printer specific operations
-  - name: Session & Login
-    description: Handle authentication related actions
-  - name: access
-    description: Access control related operations and management
 x-tagGroups:
   - name: General
     tags:
       - General
+  - name: Printer
+    tags:
+      - State
+      - Jobs
+      - Tool
+      - Bed
+      - Printhead
+      - Chamber
+      - SD Card
+      - Profiles
+
+  - name: Files
+    tags:
+      - Files
+
   - name: User Management & Access
     tags:
-      - user
+      - User
       - Groups
+      - Permissions
+  - name: System
+    tags:
+      - System
+      - Settings
+      - System Commands
+      - Languages
 paths:
   /login:
     $ref: paths/login.yaml
@@ -46,6 +77,10 @@ paths:
   /connection:
     $ref: paths/connection.yaml
 
+  # File endpoints
+  /files:
+    get:
+      $ref: paths/files/get.yaml
   /files/{location}:
     get:
       $ref: paths/files/{location}/get.yaml
@@ -56,9 +91,8 @@ paths:
       $ref: ./paths/files/{location}/{path}-get.yaml
     delete:
       $ref: ./paths/files/{location}/{path}-delete.yaml
-  /files:
+
-    get:
+  # Print job endpoints
-      $ref: paths/files/get.yaml
   /job:
     get:
       $ref: paths/job/get.yaml
@@ -93,6 +127,8 @@ paths:
   /printer/command:
     post:
       $ref: paths/printer/command/post.yaml
+
+  # Printer profile management
   /printerprofiles:
     get:
       $ref: paths/printerprofiles/get.yaml
@@ -105,6 +141,8 @@ paths:
       $ref: paths/printerprofiles/{identifier}-post.yaml
     delete:
       $ref: paths/printerprofiles/{identifier}-delete.yaml
+
+  # OctoPrint system commands
   /system/commands:
     get:
       $ref: paths/system/commands/get.yaml
@@ -114,6 +152,20 @@ paths:
   /system/commands/{source}/{action}:
     post:
       $ref: paths/system/commands/{source}-{action}-post.yaml
+
+  /settings:
+    get:
+      $ref: paths/settings/get.yaml
+    post:
+      $ref: paths/settings/post.yaml
+  /settings/templates:
+    get:
+      $ref: paths/settings/templates-get.yaml
+  /settings/apikey:
+    get:
+      $ref: paths/settings/apikey-post.yaml
+
+  # Access Controls
   /access/permissions:
     get:
       $ref: paths/access/permissions-get.yaml
@@ -154,6 +206,8 @@ paths:
       $ref: paths/access/users/{username}-apikey-post.yaml
     delete:
       $ref: paths/access/users/{username}-apikey-delete.yaml
+
+  # Language endpoints
   /languages:
     get:
       $ref: paths/languages/get.yaml

openapi/paths/access/permissions-get.yaml

@@ -2,6 +2,8 @@ summary: List all permissions
 operationId: getAllPermissions
 description: >-
   Retrieves all permissions available in the system.
+tags:
+  - Permissions
 responses:
   "200":
     description: >-

openapi/paths/access/users/get.yaml

@@ -1,7 +1,7 @@
 summary: Retrieve a list of users
 operationId: getAllUsers
 tags:
-  - user
+  - User
 description: >-
   Retrieves a list of all registered users in OctoPrint.
 responses:

openapi/paths/access/users/post.yaml

@@ -1,7 +1,7 @@
 summary: Add a new user
 operationId: addUser
 tags:
-  - user
+  - User
 description: >-
   Adds a new user to OctoPrint.
 requestBody:

openapi/paths/access/users/{username}-apikey-delete.yaml

@@ -1,7 +1,7 @@
 summary: Delete a user’s api key
 operationId: deleteApiKey
 tags:
-  - user
+  - User
 description: >-
   Deletes a user’s personal API key.
 

openapi/paths/access/users/{username}-apikey-post.yaml

@@ -1,7 +1,7 @@
 summary: Regenerate a user’s api key
 operationId: regenerateApiKey
 tags:
-  - user
+  - User
 description: >-
   Generates a new API key for the user.
 

openapi/paths/access/users/{username}-delete.yaml

@@ -3,7 +3,7 @@ operationId: deleteUser
 description: >-
   Deletes a user by name.
 tags:
-  - user
+  - User
 parameters:
   - $ref: ../../../components/parameters/username.yaml
 responses:

openapi/paths/access/users/{username}-get.yaml

@@ -1,7 +1,7 @@
 summary: Retrieve a user
 operationId: getUser
 tags:
-  - user
+  - User
 description: >-
   Retrieves information about a user.
 parameters:

openapi/paths/access/users/{username}-password-put.yaml

@@ -1,7 +1,7 @@
 summary: Change user password
 operationId: changeUserPassword
 tags:
-  - user
+  - User
 description: >-
   Changes the password of a user.
 parameters:

openapi/paths/access/users/{username}-put.yaml

@@ -1,7 +1,7 @@
 summary: Update a user
 operationId: updateUser
 tags:
-  - user
+  - User
 description: >-
   Updates an existing user.
 parameters:

openapi/paths/access/users/{username}-settings-get.yaml

@@ -1,7 +1,7 @@
 summary: Get a user's settings
 operationId: getUserSettings
 tags:
-  - user
+  - User
 description: >-
   Retrieves a user’s settings.
   Will return a 200 OK with a JSON object representing the user’s personal settings (if any) as body.

openapi/paths/access/users/{username}-settings-patch.yaml

@@ -1,7 +1,7 @@
 summary: Update a user’s settings
 operationId: updateUserSettings
 tags:
-  - user
+  - User
 description: >-
   Retrieves a user’s settings.
   Will return a 200 OK with a JSON object representing the user’s personal settings (if any) as body.

openapi/paths/connection.yaml

@@ -1,6 +1,9 @@
 get:
   summary: Printer Connection
   operationId: getConnection
+  tags:
+    - General
+    - System
   description: >-
     Retrieve the current connection settings, including information
     regarding the available baudrates and serial ports and the current
@@ -15,6 +18,9 @@ get:
 post:
   summary: Change Printer Connection
   operationId: setConnectionOptions
+  tags:
+    - General
+    - System
   requestBody:
     required: true
     content:

openapi/paths/currentuser.yaml

@@ -1,7 +1,7 @@
 get:
   tags:
-    - user
+    - User
-    - Session & Login
+    - General
   summary: Current User
   description: >-
     Retrieves information about the current user.

openapi/paths/files/get.yaml

@@ -3,6 +3,8 @@ 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.
+tags:
+  - Files
 parameters:
   - in: query
     name: recursive

openapi/paths/files/{location}/get.yaml

@@ -3,6 +3,8 @@ 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.
+tags:
+  - Files
 parameters:
   - $ref: ../../../components/parameters/fileLocation.yaml
   - $ref: ../../../components/parameters/fileRecursive.yaml

openapi/paths/files/{location}/post.yaml

@@ -1,6 +1,8 @@
 summary: Upload file or create folder
 operationId: uploadFile
 description: Upload a file to the selected location or create a new empty folder on it.
+tags:
+  - Files
 parameters:
   - $ref: ../../../components/parameters/fileLocation.yaml
 requestBody:

openapi/paths/files/{location}/{path}-delete.yaml

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

openapi/paths/files/{location}/{path}-get.yaml

@@ -1,6 +1,8 @@
 summary: Retrieve a specific file’s or folder’s information
 operationId: getFileOrFolder
 description: Retrieves the selected file’s or folder’s information.
+tags:
+  - Files
 parameters:
   - $ref: ../../../components/parameters/fileLocation.yaml
   - $ref: ../../../components/parameters/filePath.yaml

openapi/paths/files/{location}/{path}-post.yaml

@@ -1,6 +1,8 @@
 summary: Issue a file command
 operationId: sendFileCommand
 description: Issue a file command to an existing file.
+tags:
+  - Files
 parameters:
   - $ref: ../../../components/parameters/fileLocation.yaml
   - $ref: ../../../components/parameters/filePath.yaml

openapi/paths/job/get.yaml

@@ -1,6 +1,8 @@
 summary: Retrieve information about the current job
 operationId: getCurrentJob
 description: Retrieve information about the current job (if there is one).
+tags:
+  - Jobs
 requestBody:
   content:
     application/json:

openapi/paths/job/post.yaml

@@ -2,6 +2,8 @@ summary: Issue a job command
 operationId: sendJobCommand
 description: >-
   Job commands allow starting, pausing and cancelling print jobs.
+tags:
+  - Jobs
 requestBody:
   $ref: ../../components/requestBodies/JobCommand.yaml
 responses:

openapi/paths/languages/get.yaml

@@ -4,6 +4,8 @@ description: >-
   Retrieves a list of installed language packs.
 
   The response body will contain a list of available languages packs.
+tags:
+  - Languages
 responses:
   "200":
     description: >-

openapi/paths/languages/post.yaml

@@ -10,6 +10,8 @@ description: >-
   Only files with one of the extensions zip, tar.gz, tgz or tar will be processed, for other file extensions a 400 Bad Request will be returned.
 
   Will return a list of installed language packs upon completion, as described in Retrieve installed language packs.
+tags:
+  - Languages
 requestBody:
   content:
     multipart/form-data:

openapi/paths/languages/{locale}-{pack}-delete.yaml

@@ -2,6 +2,8 @@ summary: Delete a language pack
 operationId: deleteLanguagePack
 description: >-
   Deletes the language pack pack for locale locale. Can be either the _core pack (containing translations for core OctoPrint) or the language pack for a plugin specified by the plugin identifier.
+tags:
+  - Languages
 parameters:
   - in: path
     name: locale

openapi/paths/login.yaml

@@ -1,7 +1,7 @@
 post:
   tags:
-    - general
+    - General
-    - user
+    - User
   summary: Login
   description: >-
     Creates a login session or retrieves information about the currently existing session (“passive login”).

openapi/paths/logout.yaml

@@ -1,7 +1,7 @@
 post:
   tags:
-    - user
+    - User
-    - Session & Login
+    - General
   summary: Logout
   description: Ends the current login session of the current user
   operationId: logout

openapi/paths/printer/bed-get.yaml

@@ -1,5 +1,8 @@
 summary: Retrieve the current bed state
 operationId: getBedState
+tags:
+  - Bed
+  - State
 description: >-
   Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for the printer’s heated bed.
   It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history   data points can be limited using the limit query parameter.

openapi/paths/printer/bed-post.yaml

@@ -2,6 +2,8 @@ summary: Issue a bed command
 operationId: sendBedCmd
 description: >-
   Bed commands allow setting the temperature and temperature offsets for the printer’s heated bed.
+tags:
+  - Bed
 requestBody:
   $ref: ../../components/requestBodies/PrinterBedCommand.yaml
 responses:

openapi/paths/printer/chamber-get.yaml

@@ -4,6 +4,9 @@ description: >-
   Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for the printer’s heated chamber.
 
   It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history data points can be limited using the limit query parameter.
+tags:
+  - Chamber
+  - State
 parameters:
   - $ref: ../../components/parameters/history.yaml
   - $ref: ../../components/parameters/limit.yaml

openapi/paths/printer/chamber-post.yaml

@@ -2,6 +2,8 @@ summary: Issue a bed command
 operationId: sendChamberCmd
 description: >-
   Chamber commands allow setting the temperature and temperature offsets for the printer’s heated chamber.
+tags:
+  - Chamber
 requestBody:
   $ref: ../../components/requestBodies/PrinterChamberCommand.yaml
 responses:

openapi/paths/printer/command/custom-get.yaml

@@ -4,5 +4,7 @@ description: >-
   Retrieves the custom controls as configured in config.yaml.
 
   Please refer to the documentation of custom controls on what data structure to expect here.
+tags:
+  - Command
 responses:
   $ref: ../../../components/responses/CustomControls.yaml

openapi/paths/printer/command/post.yaml

@@ -2,6 +2,8 @@ summary: Send an arbitrary command to the printer
 operationId: sendPrinterCmd
 description: >-
   Sends any command to the printer via the serial interface. Should be used with some care as some commands can interfere with or even stop a running print job.
+tags:
+  - Command
 requestBody:
   content:
     application/json:

openapi/paths/printer/get.yaml

@@ -1,6 +1,8 @@
 summary: Printer State
 description: Retrieves the current state of the printer.
 operationId: getPrinterState
+tags:
+  - State
 parameters:
   - $ref: ../../components/parameters/history.yaml
   - $ref: ../../components/parameters/limit.yaml

openapi/paths/printer/printhead-post.yaml

@@ -2,6 +2,8 @@ summary: Issue a print head command
 operationId: sendPrintheadCommand
 description: >-
   Print head commands allow jogging and homing the print head in all three axes.
+tags:
+  - Printhead
 requestBody:
   $ref: ../../components/requestBodies/PrintheadCommand.yaml
 responses:

openapi/paths/printer/sd-get.yaml

@@ -6,6 +6,9 @@ description: >-
   If SD support has been disabled in OctoPrint’s settings, a 404 Not Found is returned.
 
   Returns a 200 OK with an SD State Response in the body upon success.
+tags:
+  - SD Card
+  - State
 responses:
   "200":
     description: >-

openapi/paths/printer/sd-post.yaml

@@ -2,6 +2,8 @@ summary: Issue an SD command
 operationId: sendSdCmd
 description: >-
   SD commands allow initialization, refresh and release of the printer’s SD card (if available).
+tags:
+  - SD Card
 requestBody:
   $ref: ../../components/requestBodies/PrinterSdCommand.yaml
 responses:

openapi/paths/printer/tool-get.yaml

@@ -2,6 +2,9 @@ summary: Retrieve the current tool state
 operationId: getToolState
 description: >-
   Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for all of the printer’s available tools. It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history data points can be limited using the limit query parameter.
+tags:
+  - Tool
+  - State
 parameters:
   - $ref: ../../components/parameters/history.yaml
   - $ref: ../../components/parameters/limit.yaml

openapi/paths/printer/tool-post.yaml

@@ -2,6 +2,8 @@ summary: Issue a tool command
 operationId: sendToolCmd
 description: >-
   Tool commands allow setting the temperature and temperature offsets for the printer’s tools (hotends), selecting the current tool and extruding/retracting from the currently selected tool.
+tags:
+  - Tool
 requestBody:
   $ref: ../../components/requestBodies/PrinterToolCommand.yaml
 responses:

openapi/paths/printerprofiles/get.yaml

@@ -2,9 +2,11 @@ summary: Retrieve all printer profiles
 operationId: getPrinterProfiles
 description: >-
   Retrieves a list of all configured printer profiles.
+tags:
+  - Profiles
 responses:
   "200":
-    description: >- 
+    description: >-
       List of available printer profiles
     content:
       application/json:
@@ -14,4 +16,4 @@ responses:
             profiles:
               type: array
               items:
-                $ref: ../../components/schemas/printer/Profile.yaml
+                $ref: ../../components/schemas/printer/Profile.yaml

openapi/paths/printerprofiles/post.yaml

@@ -3,12 +3,14 @@ operationId: addNewPrinterProfile
 description: >-
   Adds a new printer profile based on either the current default profile or the profile identified in basedOn.
   The provided profile data will be merged with the profile data from the base profile.
+tags:
+  - Profiles
 requestBody:
   content:
     application/json:
       schema:
         type: object
-        required: 
+        required:
           - profile
         properties:
           basedOn:
@@ -18,7 +20,7 @@ requestBody:
             required: false
 responses:
   "200":
-    description: >- 
+    description: >-
       Profile saved.
     content:
       application/json:
@@ -27,4 +29,3 @@ responses:
           properties:
             profile:
               $ref: ../../components/schemas/printer/Profile.yaml
-

openapi/paths/printerprofiles/{identifier}-delete.yaml

@@ -4,10 +4,12 @@ description: >-
   Deletes an existing printer profile by its profile identifier.
 parameters:
   - $ref: ../../components/parameters/profileIdentifier.yaml
+tags:
+  - Profiles
 responses:
   "204":
-    description: >- 
+    description: >-
       Profile removed
   "409":
     description: >-
-      If the profile to be deleted is the currently selected profile, a 409 Conflict will be returned.
+      If the profile to be deleted is the currently selected profile, a 409 Conflict will be returned.

openapi/paths/printerprofiles/{identifier}-get.yaml

@@ -2,11 +2,13 @@ summary: Retrieve a single printer profile
 operationId: getPrinterProfile
 description: >-
   Retrieves an existing single printer profile.
+tags:
+  - Profiles
 parameters:
   - $ref: ../../components/parameters/profileIdentifier.yaml
 responses:
   "200":
-    description: >- 
+    description: >-
       List of available printer profiles
     content:
       application/json:
@@ -14,4 +16,4 @@ responses:
           $ref: ../../components/schemas/printer/Profile.yaml
   "404":
     description: >-
-      The profile does not exist
+      The profile does not exist

openapi/paths/printerprofiles/{identifier}-post.yaml

@@ -3,13 +3,15 @@ operationId: updatePrinterProfile
 description: >-
   Adds a new printer profile based on either the current default profile or the profile identified in basedOn.
   The provided profile data will be merged with the profile data from the base profile.
+tags:
+  - Profiles
 parameters:
   - $ref: ../../components/parameters/profileIdentifier.yaml
 requestBody:
   $ref: "../../components/requestBodies/PrinterProfileChange.yaml"
 responses:
   "200":
-    description: >- 
+    description: >-
       Profile saved.
     content:
       application/json:
@@ -18,4 +20,3 @@ responses:
           properties:
             profile:
               $ref: ../../components/schemas/printer/Profile.yaml
-

openapi/paths/settings/apikey-post.yaml

@@ -4,10 +4,13 @@ description: >-
   Generates a new system wide API key.
 
   Does not expect a body. Will return the generated API key as apikey property in the JSON object contained in the response body.
+tags:
+  - System
+  - Settings
 responses:
   "200":
     description: >-
       ApiKey was regenerated
   "403":
     description: >-
-      No admin rights
+      No admin rights

openapi/paths/settings/get.yaml

@@ -2,6 +2,8 @@ summary: Retrieve current settings
 operationId: getSettings
 description: >-
   Retrieves the current configuration of OctoPrint.
+tags:
+  - Settings
 responses:
   "200":
     description: >-
@@ -9,4 +11,4 @@ responses:
     content:
       application/json:
         schema:
-          $ref: ../../components/schemas/Config.yaml
+          $ref: ../../components/schemas/Config.yaml

openapi/paths/settings/post.yaml

@@ -4,6 +4,8 @@ description: >-
   Saves the provided settings in OctoPrint.
 
   Expects a JSON object with the settings to change as request body. This can be either a full settings tree, or only a partial tree containing only those fields that should be updated.
+tags:
+  - Settings
 requestBody:
   content:
     application/json:
@@ -16,4 +18,4 @@ responses:
     content:
       application/json:
         schema:
-          $ref: ../../components/schemas/Config.yaml
+          $ref: ../../components/schemas/Config.yaml

openapi/paths/settings/templates-get.yaml

@@ -4,6 +4,9 @@ description: >-
   Fetch data (currently only the sorting order) of all registered template components in the system.
 
   Use this to get a full list of the identifiers of all UI components provided either by core OctoPrint or any currently active plugins.
+tags:
+  - Settings
+  - Templates
 responses:
   "200":
     description: >-
@@ -11,4 +14,4 @@ responses:
     content:
       application/json:
         schema:
-          $ref: ../../components/schemas/Templates.yaml
+          $ref: ../../components/schemas/Templates.yaml

openapi/paths/system/commands/get.yaml

@@ -2,6 +2,8 @@ summary: List all registered system commands
 operationId: getSystemCmds
 description: >-
   Retrieves all configured system commands.
+tags:
+  - System Commands
 responses:
   "200":
     description: >-
@@ -14,4 +16,4 @@ responses:
             core:
               type: array
               items:
-                $ref: ../../../components/schemas/system/ClientCmd.yaml
+                $ref: ../../../components/schemas/system/ClientCmd.yaml

openapi/paths/system/commands/{source}-get.yaml

@@ -2,6 +2,8 @@ summary: List all registered system commands for a source
 operationId: getSystemSourceCmds
 description: >-
   Retrieves the configured system commands for the specified source.
+tags:
+  - System Commands
 parameters:
   - $ref: ../../../components/parameters/systemCmdSource.yaml
 responses:
@@ -13,4 +15,4 @@ responses:
         schema:
           type: array
           items:
-            $ref: ../../../components/schemas/system/ClientCmd.yaml
+            $ref: ../../../components/schemas/system/ClientCmd.yaml

openapi/paths/system/commands/{source}-{action}-post.yaml

@@ -2,6 +2,8 @@ summary: Execute a registered system command
 operationId: executeSysCmd
 description: >-
   Execute the system command action defined in source.
+tags:
+  - System Commands
 parameters:
   - $ref: ../../../components/parameters/systemCmdSource.yaml
   - in: path

openapi/paths/version.yaml

@@ -6,6 +6,9 @@ get:
     version, text containing the server version including the prefix ``OctoPrint
     `` (to determine that this is indeed a genuine OctoPrint instance).
   operationId: getVersion
+  tags:
+    - General
+    - System
   responses:
     "200":
       description: OctoPrint server version