added HTTP API swagger file
This commit is contained in:
john30
@@ -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.
|
||||
Reference in New Issue
Block a user