From d2fab9fe5639948042f55fb4ea5e81cbb6fa96a8 Mon Sep 17 00:00:00 2001 From: John Date: Mon, 5 Apr 2021 10:06:22 +0200 Subject: [PATCH] switch to openapi --- contrib/html/openapi.yaml | 759 ++++++++++++++++++++++++++++++++++++++ contrib/html/swagger.yaml | 457 ----------------------- 2 files changed, 759 insertions(+), 457 deletions(-) create mode 100644 contrib/html/openapi.yaml delete mode 100644 contrib/html/swagger.yaml diff --git a/contrib/html/openapi.yaml b/contrib/html/openapi.yaml new file mode 100644 index 000000000..39d933f96 --- /dev/null +++ b/contrib/html/openapi.yaml @@ -0,0 +1,759 @@ +openapi: 3.0.1 +info: + title: ebusd-http + description: The API that ebusd provides on HTTP port. + version: "21.3" +servers: + - url: http://127.0.0.1:8080/ +paths: + /data: + get: + summary: Get all messages of all circuits. + parameters: + - name: since + in: query + description: limit to messages that have changed since the specified UTC seconds. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + - name: poll + in: query + description: set the poll priority of matching message(s) to prio. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + - name: verbose + in: query + description: include comments and field units. + allowEmptyValue: false + schema: + type: boolean + - name: indexed + in: query + description: always return field indexes instead of names. + allowEmptyValue: false + schema: + type: boolean + - name: numeric + in: query + description: return numeric values of value list entries. + allowEmptyValue: false + schema: + type: boolean + - name: valuename + in: query + description: include value and name for named values. + allowEmptyValue: false + schema: + type: boolean + - name: full + in: query + description: include all available attributes. + allowEmptyValue: false + schema: + type: boolean + - name: required + in: query + description: retrieve the data from the bus if not yet cached. + allowEmptyValue: false + schema: + type: boolean + - name: write + in: query + description: retrieve write messages in addition to read/poll messages. + allowEmptyValue: false + schema: + type: boolean + - name: raw + in: query + description: include raw master/slave data. + allowEmptyValue: false + schema: + type: boolean + - name: def + in: query + description: include message and field definition. + allowEmptyValue: false + schema: + type: boolean + - name: user + in: query + description: authenticate with user name. + allowEmptyValue: false + schema: + type: string + - name: secret + in: query + description: authenticate with user secret. + allowEmptyValue: false + schema: + type: string + responses: + 200: + description: Success. + content: + application/json;charset=utf-8: + schema: + $ref: '#/components/schemas/Data' + 400: + description: Invalid request parameters. + content: { } + 403: + description: User not authorized. + content: { } + 404: + description: Circuit or message not found. + content: { } + 500: + description: General error. + content: { } + /data/{circuit}: + get: + summary: Get all messages of a particular circuit. + parameters: + - name: circuit + in: path + required: true + schema: + type: string + - name: since + in: query + description: limit to messages that have changed since the specified UTC seconds. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + - name: poll + in: query + description: set the poll priority of matching message(s) to prio. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + - name: exact + in: query + description: exact search for circuit/message name. + allowEmptyValue: false + schema: + type: boolean + - name: verbose + in: query + description: include comments and field units. + allowEmptyValue: false + schema: + type: boolean + - name: indexed + in: query + description: always return field indexes instead of names. + allowEmptyValue: false + schema: + type: boolean + - name: numeric + in: query + description: return numeric values of value list entries. + allowEmptyValue: false + schema: + type: boolean + - name: valuename + in: query + description: include value and name for named values. + allowEmptyValue: false + schema: + type: boolean + - name: full + in: query + description: include all available attributes. + allowEmptyValue: false + schema: + type: boolean + - name: required + in: query + description: retrieve the data from the bus if not yet cached. + allowEmptyValue: false + schema: + type: boolean + - name: write + in: query + description: retrieve write messages in addition to read/poll messages. + allowEmptyValue: false + schema: + type: boolean + - name: raw + in: query + description: include raw master/slave data. + allowEmptyValue: false + schema: + type: boolean + - name: def + in: query + description: include message and field definition. + allowEmptyValue: false + schema: + type: boolean + - name: user + in: query + description: authenticate with user name. + allowEmptyValue: false + schema: + type: string + - name: secret + in: query + description: authenticate with user secret. + allowEmptyValue: false + schema: + type: string + responses: + 200: + description: Success. + content: + application/json;charset=utf-8: + schema: + $ref: '#/components/schemas/Data' + 400: + description: Invalid request parameters. + content: { } + 403: + description: User not authorized. + content: { } + 404: + description: Circuit or message not found. + content: { } + 500: + description: General error. + content: { } + /data/{circuit}/{message}: + get: + summary: Get a particular message of a particular circuit. + parameters: + - name: circuit + in: path + required: true + schema: + type: string + - name: message + in: path + required: true + schema: + type: string + - name: since + in: query + description: limit to messages that have changed since the specified UTC seconds. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + - name: poll + in: query + description: set the poll priority of matching message(s) to prio. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + - name: exact + in: query + description: exact search for circuit/message name. + allowEmptyValue: false + schema: + type: boolean + - name: verbose + in: query + description: include comments and field units. + allowEmptyValue: false + schema: + type: boolean + - name: indexed + in: query + description: always return field indexes instead of names. + allowEmptyValue: false + schema: + type: boolean + - name: numeric + in: query + description: return numeric values of value list entries. + allowEmptyValue: false + schema: + type: boolean + - name: valuename + in: query + description: include value and name for named values. + allowEmptyValue: false + schema: + type: boolean + - name: full + in: query + description: include all available attributes. + allowEmptyValue: false + schema: + type: boolean + - name: required + in: query + description: retrieve the data from the bus if not yet cached. + allowEmptyValue: false + schema: + type: boolean + - name: write + in: query + description: retrieve write messages in addition to read/poll messages. + allowEmptyValue: false + schema: + type: boolean + - name: raw + in: query + description: include raw master/slave data. + allowEmptyValue: false + schema: + type: boolean + - name: def + in: query + description: include message and field definition. + allowEmptyValue: false + schema: + type: boolean + - name: user + in: query + description: authenticate with user name. + allowEmptyValue: false + schema: + type: string + - name: secret + in: query + description: authenticate with user secret. + allowEmptyValue: false + schema: + type: string + responses: + 200: + description: Success + content: + application/json;charset=utf-8: + schema: + $ref: '#/components/schemas/Data' + 500: + description: Circuit or message not found. + content: { } + /{file}: + get: + summary: Retrieve a particular file. + parameters: + - name: file + in: path + description: the file to retrieve. + required: true + schema: + type: string + responses: + 200: + description: Success + content: + text/html: + schema: + type: string + format: binary + text/css: + schema: + type: string + format: binary + application/javascript: + schema: + type: string + format: binary + image/png: + schema: + type: string + format: binary + image/jpeg: + schema: + type: string + format: binary + image/svg+xml: + schema: + type: string + format: binary + application/json;charset=utf-8: + schema: + type: string + format: binary + application/yaml;charset=utf-8: + schema: + type: string + format: binary + 400: + description: Invalid request parameters. + content: { } + 403: + description: User not authorized. + content: { } + 404: + description: Circuit or message not found. + content: { } + 500: + description: General error. + content: { } + head: + summary: Retrieve headers for a certain file. + parameters: + - name: file + in: path + description: the file to retrieve. + required: true + schema: + type: string + responses: + 200: + description: Success + content: + application/json;charset=utf-8: + schema: + $ref: '#/components/schemas/Data' + 400: + description: Circuit or message not found. + content: { } + +components: + schemas: + Global: + required: + - lastup + - masters + - messages + - reconnects + - signal + - version + type: object + properties: + version: + pattern: '[0-9]+\.[0-9]+\.[0-9a-f]+\.' + type: string + description: the ebusd version (major.minor.sha1 or major.minor.date). + example: 3.0.1234abc + updatecheck: + type: string + description: the result of update check ("OK" or string describing available + updates). + example: revision 1234abd available, 5 newer configuration files available + signal: + type: boolean + description: whether signal is available. + example: true + symbolrate: + minimum: 0 + type: integer + description: the current symbol rate on the bus. + example: 31 + maxsymbolrate: + minimum: 0 + type: integer + description: the maximum symbol rate on the bus seen since start. + example: 167 + qq: + maximum: 255 + minimum: 0 + type: integer + description: the ebusd master address (only if not readonly). + example: 49 + reconnects: + minimum: 0 + type: integer + description: the number of reconnects to the device since start. + example: 0 + masters: + minimum: 0 + type: integer + description: the number of masters recognized on the bus. + example: 5 + messages: + minimum: 0 + type: integer + description: the number of known message definitions. + example: 893 + lastup: + minimum: 0 + type: integer + description: the time in UTC seconds of the last update of any message. + example: 1493483370 + Circuit: + type: object + properties: + name: + type: string + description: the circuit name. + zz: + maximum: 255 + minimum: 0 + type: integer + description: the circuit slave address. + example: 8 + messages: + type: object + additionalProperties: + $ref: '#/components/schemas/Message' + Message: + required: + - lastup + - name + - passive + - write + type: object + properties: + name: + type: string + description: the message name. + passive: + type: boolean + description: true when this is a passive message. + write: + type: boolean + description: true for a write message, false for a read message. + lastup: + minimum: 0 + type: integer + description: the time in UTC seconds of the last update of the message (0 + for never). + qq: + maximum: 255 + minimum: 0 + type: integer + description: limited source master address (only with def). + example: 49 + zz: + maximum: 255 + minimum: 0 + type: integer + description: destination master or slave address. + example: 8 + id: + type: array + description: the message ID composed of PBSB and further master data bytes + (only with def). + items: + maximum: 255 + minimum: 0 + type: integer + comment: + type: string + description: the message comment (only with verbose). + master: + type: array + description: the last seen master data bytes (only with raw and if available). + items: + maximum: 255 + minimum: 0 + type: integer + slave: + type: array + description: the last seen slave data bytes (only with raw and if available). + items: + maximum: 255 + minimum: 0 + type: integer + fields: + type: object + additionalProperties: + $ref: '#/components/schemas/Field' + description: the decoded fields the message is composed of (only if available). + fielddefs: + type: array + description: the field definitions the message is composed of (only with + def). + items: + $ref: '#/components/schemas/FieldDef' + Field: + type: object + properties: + name: + type: string + description: the field name. + value: + type: object + description: the field value. + unit: + type: string + description: the field unit (only with verbose). + comment: + type: string + description: the field comment (only with verbose). + FieldDef: + required: + - isbits + - length + - name + - slave + - type + type: object + properties: + name: + type: string + description: the field name. + slave: + type: boolean + description: whether the field is part of the slave data. + type: + type: string + description: the field type. + isbits: + type: boolean + description: true when the length is in bits. + length: + type: number + description: the field length in bytes (-1 for remainder, number of bits + when isbits is true). + divisor: + type: number + description: the extra divisor applied to the raw value (only if applicable). + value: + type: string + description: the constant value (only if applicable). + verify: + type: boolean + description: whether the constant value is verified when decoding (only + if applicable). + values: + type: object + additionalProperties: + type: string + description: the value name. + description: the raw numeric value to name assignments (only if applicable). + unit: + type: string + description: the field unit. + comment: + type: string + description: the field comment. + Data: + required: + - global + type: object + properties: + global: + $ref: '#/components/schemas/Global' + additionalProperties: + $ref: '#/components/schemas/Circuit' + responses: + BadRequest: + description: Invalid request parameters. + content: { } + GeneralError: + description: General error. + content: { } + NotAuthorized: + description: User not authorized. + content: { } + NotFound: + description: Circuit or message not found. + content: { } + parameters: + circuitParam: + name: circuit + in: path + required: true + schema: + type: string + messageParam: + name: message + in: path + required: true + schema: + type: string + sinceQuery: + name: since + in: query + description: limit to messages that have changed since the specified UTC seconds. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + pollQuery: + name: poll + in: query + description: set the poll priority of matching message(s) to prio. + allowEmptyValue: false + schema: + minimum: 0 + type: integer + exactQuery: + name: exact + in: query + description: exact search for circuit/message name. + allowEmptyValue: false + schema: + type: boolean + verboseQuery: + name: verbose + in: query + description: include comments and field units. + allowEmptyValue: false + schema: + type: boolean + indexedQuery: + name: indexed + in: query + description: always return field indexes instead of names. + allowEmptyValue: false + schema: + type: boolean + numericQuery: + name: numeric + in: query + description: return numeric values of value list entries. + allowEmptyValue: false + schema: + type: boolean + valuenameQuery: + name: valuename + in: query + description: include value and name for named values. + allowEmptyValue: false + schema: + type: boolean + fullQuery: + name: full + in: query + description: include all available attributes. + allowEmptyValue: false + schema: + type: boolean + requiredQuery: + name: required + in: query + description: retrieve the data from the bus if not yet cached. + allowEmptyValue: false + schema: + type: boolean + writeQuery: + name: write + in: query + description: retrieve write messages in addition to read/poll messages. + allowEmptyValue: false + schema: + type: boolean + rawQuery: + name: raw + in: query + description: include raw master/slave data. + allowEmptyValue: false + schema: + type: boolean + defQuery: + name: def + in: query + description: include message and field definition. + allowEmptyValue: false + schema: + type: boolean + userQuery: + name: user + in: query + description: authenticate with user name. + allowEmptyValue: false + schema: + type: string + secretQuery: + name: secret + in: query + description: authenticate with user secret. + allowEmptyValue: false + schema: + type: string + diff --git a/contrib/html/swagger.yaml b/contrib/html/swagger.yaml deleted file mode 100644 index 7c94e84da..000000000 --- a/contrib/html/swagger.yaml +++ /dev/null @@ -1,457 +0,0 @@ -swagger: '2.0' -info: - title: ebusd-http - description: The API that ebusd provides on HTTP port. - version: '3.0' -schemes: - - http -produces: - - 'application/json;charset=utf-8' -host: '127.0.0.1:8080' -paths: - /data: - get: - summary: Get all messages of all circuits. - responses: - '200': - description: Success. - schema: - $ref: '#/definitions/Data' - '400': - $ref: '#/responses/BadRequest' - '403': - $ref: '#/responses/NotAuthorized' - '404': - $ref: '#/responses/NotFound' - '500': - $ref: '#/responses/GeneralError' - parameters: - - $ref: '#/parameters/sinceQuery' - - $ref: '#/parameters/pollQuery' - - $ref: '#/parameters/verboseQuery' - - $ref: '#/parameters/indexedQuery' - - $ref: '#/parameters/numericQuery' - - $ref: '#/parameters/valuenameQuery' - - $ref: '#/parameters/fullQuery' - - $ref: '#/parameters/requiredQuery' - - $ref: '#/parameters/writeQuery' - - $ref: '#/parameters/rawQuery' - - $ref: '#/parameters/defQuery' - - $ref: '#/parameters/userQuery' - - $ref: '#/parameters/secretQuery' - /data/{circuit}: - get: - summary: Get all messages of a particular circuit. - responses: - '200': - description: Success. - schema: - $ref: '#/definitions/Data' - '400': - $ref: '#/responses/BadRequest' - '403': - $ref: '#/responses/NotAuthorized' - '404': - $ref: '#/responses/NotFound' - '500': - $ref: '#/responses/GeneralError' - parameters: - - $ref: '#/parameters/circuitParam' - - $ref: '#/parameters/sinceQuery' - - $ref: '#/parameters/pollQuery' - - $ref: '#/parameters/exactQuery' - - $ref: '#/parameters/verboseQuery' - - $ref: '#/parameters/indexedQuery' - - $ref: '#/parameters/numericQuery' - - $ref: '#/parameters/valuenameQuery' - - $ref: '#/parameters/fullQuery' - - $ref: '#/parameters/requiredQuery' - - $ref: '#/parameters/writeQuery' - - $ref: '#/parameters/rawQuery' - - $ref: '#/parameters/defQuery' - - $ref: '#/parameters/userQuery' - - $ref: '#/parameters/secretQuery' - /data/{circuit}/{message}: - get: - summary: Get a particular message of a particular circuit. - responses: - '500': - $ref: '#/responses/NotFound' - '200': - description: Success - schema: - $ref: '#/definitions/Data' - parameters: - - $ref: '#/parameters/circuitParam' - - $ref: '#/parameters/messageParam' - - $ref: '#/parameters/sinceQuery' - - $ref: '#/parameters/pollQuery' - - $ref: '#/parameters/exactQuery' - - $ref: '#/parameters/verboseQuery' - - $ref: '#/parameters/indexedQuery' - - $ref: '#/parameters/numericQuery' - - $ref: '#/parameters/valuenameQuery' - - $ref: '#/parameters/fullQuery' - - $ref: '#/parameters/requiredQuery' - - $ref: '#/parameters/writeQuery' - - $ref: '#/parameters/rawQuery' - - $ref: '#/parameters/defQuery' - - $ref: '#/parameters/userQuery' - - $ref: '#/parameters/secretQuery' - /{file}: - get: - summary: Retrieve a particular file. - responses: - '200': - description: Success - schema: - type: 'file' - '400': - $ref: '#/responses/BadRequest' - '403': - $ref: '#/responses/NotAuthorized' - '404': - $ref: '#/responses/NotFound' - '500': - $ref: '#/responses/GeneralError' - produces: - - text/html - - text/css - - application/javascript - - image/png - - image/jpeg - - image/svg+xml - - 'application/json;charset=utf-8' - - 'application/yaml;charset=utf-8' - head: - summary: Retrieve headers for a certain file. - responses: - '400': - $ref: '#/responses/NotFound' - '200': - description: Success - schema: - $ref: '#/definitions/Data' - parameters: - - name: file - in: path - required: true - description: the file to retrieve. - type: string -definitions: - Global: - type: object - properties: - version: - type: string - description: the ebusd version (major.minor.sha1 or major.minor.date). - pattern: '[0-9]+\.[0-9]+\.[0-9a-f]+\.' - example: '3.0.1234abc' - updatecheck: - type: string - description: the result of update check ("OK" or string describing available updates). - example: 'revision 1234abd available, 5 newer configuration files available' - signal: - type: boolean - description: whether signal is available. - example: true - symbolrate: - type: integer - description: the current symbol rate on the bus. - minimum: 0 - example: 31 - maxsymbolrate: - type: integer - description: the maximum symbol rate on the bus seen since start. - minimum: 0 - example: 167 - qq: - type: integer - description: the ebusd master address (only if not readonly). - minimum: 0 - maximum: 255 - example: 49 - reconnects: - type: integer - description: the number of reconnects to the device since start. - minimum: 0 - example: 0 - masters: - type: integer - description: the number of masters recognized on the bus. - minimum: 0 - example: 5 - messages: - type: integer - description: the number of known message definitions. - minimum: 0 - example: 893 - lastup: - type: integer - description: the time in UTC seconds of the last update of any message. - minimum: 0 - example: 1493483370 - required: - - version - - signal - - reconnects - - masters - - messages - - lastup - Circuit: - type: object - properties: - name: - type: string - description: the circuit name. - zz: - type: integer - description: the circuit slave address. - minimum: 0 - maximum: 255 - example: 8 - messages: - type: object - additionalProperties: - $ref: '#/definitions/Message' - Message: - type: object - properties: - name: - type: string - description: the message name. - passive: - type: boolean - description: true when this is a passive message. - write: - type: boolean - description: true for a write message, false for a read message. - lastup: - type: integer - description: the time in UTC seconds of the last update of the message (0 for never). - minimum: 0 - qq: - type: integer - description: limited source master address (only with def). - minimum: 0 - maximum: 255 - example: 49 - zz: - type: integer - description: destination master or slave address. - minimum: 0 - maximum: 255 - example: 8 - id: - type: array - description: the message ID composed of PBSB and further master data bytes (only with def). - items: - type: integer - minimum: 0 - maximum: 255 - comment: - type: string - description: the message comment (only with verbose). - master: - type: array - description: the last seen master data bytes (only with raw and if available). - items: - type: integer - minimum: 0 - maximum: 255 - slave: - type: array - description: the last seen slave data bytes (only with raw and if available). - items: - type: integer - minimum: 0 - maximum: 255 - fields: - type: object - description: the decoded fields the message is composed of (only if available). - additionalProperties: - $ref: '#/definitions/Field' - fielddefs: - type: array - description: the field definitions the message is composed of (only with def). - items: - $ref: '#/definitions/FieldDef' - required: - - name - - passive - - write - - lastup - Field: - type: object - properties: - name: - type: string - description: the field name. - value: - description: the field value. - unit: - type: string - description: the field unit (only with verbose). - comment: - type: string - description: the field comment (only with verbose). - FieldDef: - type: object - properties: - name: - type: string - description: the field name. - slave: - type: boolean - description: whether the field is part of the slave data. - type: - type: string - description: the field type. - isbits: - type: boolean - description: true when the length is in bits. - length: - type: number - description: the field length in bytes (-1 for remainder, number of bits when isbits is true). - divisor: - type: number - description: the extra divisor applied to the raw value (only if applicable). - value: - type: string - description: the constant value (only if applicable). - verify: - type: boolean - description: whether the constant value is verified when decoding (only if applicable). - values: - type: object - description: the raw numeric value to name assignments (only if applicable). - additionalProperties: - type: string - description: the value name. - unit: - type: string - description: the field unit. - comment: - type: string - description: the field comment. - required: - - name - - slave - - type - - isbits - - length - Data: - type: object - properties: - global: - $ref: '#/definitions/Global' - additionalProperties: - $ref: '#/definitions/Circuit' - required: - - global -parameters: - circuitParam: - name: circuit - in: path - required: true - type: string - messageParam: - name: message - in: path - required: true - type: string - sinceQuery: - name: since - in: query - description: limit to messages that have changed since the specified UTC seconds. - type: integer - minimum: 0 - allowEmptyValue: false - pollQuery: - name: poll - in: query - description: set the poll priority of matching message(s) to prio. - type: integer - minimum: 0 - allowEmptyValue: false - exactQuery: - name: exact - in: query - description: exact search for circuit/message name. - type: boolean - allowEmptyValue: false - verboseQuery: - name: verbose - in: query - description: include comments and field units. - type: boolean - allowEmptyValue: false - indexedQuery: - name: indexed - in: query - description: always return field indexes instead of names. - type: boolean - allowEmptyValue: false - numericQuery: - name: numeric - in: query - description: return numeric values of value list entries. - type: boolean - allowEmptyValue: false - valuenameQuery: - name: valuename - in: query - description: include value and name for named values. - type: boolean - allowEmptyValue: false - fullQuery: - name: full - in: query - description: include all available attributes. - type: boolean - allowEmptyValue: false - requiredQuery: - name: required - in: query - description: retrieve the data from the bus if not yet cached. - type: boolean - allowEmptyValue: false - writeQuery: - name: write - in: query - description: retrieve write messages in addition to read/poll messages. - type: boolean - allowEmptyValue: false - rawQuery: - name: raw - in: query - description: include raw master/slave data. - type: boolean - allowEmptyValue: false - defQuery: - name: def - in: query - description: include message and field definition. - type: boolean - allowEmptyValue: false - userQuery: - name: user - in: query - description: authenticate with user name. - type: string - allowEmptyValue: false - secretQuery: - name: secret - in: query - description: authenticate with user secret. - type: string - allowEmptyValue: false -responses: - BadRequest: - description: Invalid request parameters. - NotFound: - description: Circuit or message not found. - NotAuthorized: - description: User not authorized. - GeneralError: - description: General error. \ No newline at end of file