From 576d8a34c0c9a16dc9b223be62302c9f06288d97 Mon Sep 17 00:00:00 2001 From: Wlad Date: Thu, 22 Oct 2020 21:58:34 +0200 Subject: [PATCH] add description and summary --- openapi/paths/connection.yaml | 21 +++++++++++++-------- openapi/paths/currentuser.yaml | 7 +++++-- openapi/paths/login.yaml | 12 +++++++++--- openapi/paths/logout.yaml | 6 ++++-- openapi/paths/printer.yaml | 7 +++++-- openapi/paths/printer@tool.yaml | 4 +++- openapi/paths/version.yaml | 14 ++++++++------ 7 files changed, 47 insertions(+), 24 deletions(-) diff --git a/openapi/paths/connection.yaml b/openapi/paths/connection.yaml index 34fd39f..fa9699a 100644 --- a/openapi/paths/connection.yaml +++ b/openapi/paths/connection.yaml @@ -1,15 +1,20 @@ get: + summary: Printer Connection + operationId: getConnection + description: >- + Retrieve the current connection settings, including information + regarding the available baudrates and serial ports and the current + connection state. responses: - '200': - description: >- - Retrieve the current connection settings, including information - regarding the available baudrates and serial ports and the current - connection state. + "200": + description: Connection info object content: application/json: schema: $ref: ../components/schemas/ConnectionInfo.yaml post: + summary: Change Printer Connection + operationId: setConnectionOptions requestBody: required: true content: @@ -22,9 +27,9 @@ post: discriminator: propertyName: command responses: - '204': - description: success - '400': + "204": + description: Printer connection settings changed + "400": description: >- If the selected port or baudrate for a connect command are not part of the available options. diff --git a/openapi/paths/currentuser.yaml b/openapi/paths/currentuser.yaml index b70720f..eb245c1 100644 --- a/openapi/paths/currentuser.yaml +++ b/openapi/paths/currentuser.yaml @@ -1,7 +1,10 @@ -description: Retrieves information about the current user. get: + summary: Current User + description: >- + Retrieves information about the current user. + operationId: getCurrentUser responses: - '200': + "200": description: Current user object content: application/json: diff --git a/openapi/paths/login.yaml b/openapi/paths/login.yaml index def983c..41f6852 100644 --- a/openapi/paths/login.yaml +++ b/openapi/paths/login.yaml @@ -1,4 +1,10 @@ post: + summary: Login + description: >- + Creates a login session or retrieves information about the currently existing session (“passive login”). + Can be used in one of two ways: to login a user via username and password and create a persistent session (usually from a UI in the browser), or to retrieve information about the active user (from an existing session or an API key) via the passive flag. + Will return a 200 OK with a login response on successful login, whether active or passive. The active (username/password) login may also return a 403 Forbidden in case of a username/password mismatch, unknown user or a deactivated account. + operationId: login requestBody: required: true content: @@ -8,11 +14,11 @@ post: - $ref: ../components/schemas/Login.yaml - $ref: ../components/schemas/PassiveLogin.yaml responses: - '200': + "200": description: Successful login content: application/json: schema: $ref: ../components/schemas/LoginResponse.yaml - '403': - description: 'Username/password mismatch, unknown user or deactivated account' + "403": + description: "Username/password mismatch, unknown user or deactivated account" diff --git a/openapi/paths/logout.yaml b/openapi/paths/logout.yaml index 6822c66..cc8dc3c 100644 --- a/openapi/paths/logout.yaml +++ b/openapi/paths/logout.yaml @@ -1,5 +1,7 @@ -description: Ends the current login session of the current user. post: + summary: Logout User + description: Ends the current login session of the current user + operationId: logout responses: - '204': + "204": description: User logged out diff --git a/openapi/paths/printer.yaml b/openapi/paths/printer.yaml index 1023917..cada1fd 100644 --- a/openapi/paths/printer.yaml +++ b/openapi/paths/printer.yaml @@ -1,4 +1,7 @@ get: + summary: Printer State + description: Retrieves the current state of the printer. + operationId: getPrinterState responses: - '200': - description: Retrieves the current state of the printer. + "200": + description: Current Printer state. diff --git a/openapi/paths/printer@tool.yaml b/openapi/paths/printer@tool.yaml index b5d0308..4f938a1 100644 --- a/openapi/paths/printer@tool.yaml +++ b/openapi/paths/printer@tool.yaml @@ -1,8 +1,10 @@ get: + summary: Printer Tool State 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. + operationId: getToolState responses: - '200': + "200": description: Current tool state diff --git a/openapi/paths/version.yaml b/openapi/paths/version.yaml index 890d830..8438bc1 100644 --- a/openapi/paths/version.yaml +++ b/openapi/paths/version.yaml @@ -1,11 +1,13 @@ -description: >- - Retrieve information regarding server and API version. Returns a JSON object - with two keys, api containing the API version, server containing the server - version, text containing the server version including the prefix ``OctoPrint - `` (to determine that this is indeed a genuine OctoPrint instance). get: + summary: Version + description: >- + Retrieve information regarding server and API version. Returns a JSON object + with two keys, api containing the API version, server containing the server + version, text containing the server version including the prefix ``OctoPrint + `` (to determine that this is indeed a genuine OctoPrint instance). + operationId: getVersion responses: - '200': + "200": description: OctoPrint server version content: application/json: