From 3d4d876d5ee1ea359debb8d40bf58745eac3c422 Mon Sep 17 00:00:00 2001 From: john30 Date: Sat, 29 Apr 2017 21:00:32 +0200 Subject: [PATCH] added HTTP API swagger file --- contrib/html/swagger.yaml | 326 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 contrib/html/swagger.yaml diff --git a/contrib/html/swagger.yaml b/contrib/html/swagger.yaml new file mode 100644 index 00000000..8e8f316a --- /dev/null +++ b/contrib/html/swagger.yaml @@ -0,0 +1,326 @@ +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' +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/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/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/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' + 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.abcdefg' + updatecheck: + type: string + description: the result of update check ("OK" or string describing available updates). + example: 'revision abcdefh 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 + 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 + items: + $ref: '#/definitions/Message' + Message: + type: object + properties: + lastup: + type: integer + description: the time in UTC seconds of the last update of the message. + minimum: 0 + zz: + type: string + description: destination bus address. + pattern: '[0-9a-f]{2}' + comment: + type: string + description: the message comment (only with verbose). + fields: + type: object + items: + $ref: '#/definitions/Field' + 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. + required: + - lastup + - passive + - write + 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). + Data: + type: object + properties: + global: + $ref: '#/definitions/Global' + items: + $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: 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 + 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