|
|
|
@ -67,16 +67,16 @@ OpenAPI
|
|
|
|
|
|
|
|
|
|
When writing OpenAPI specifications for the API endpoints, follow these rules:
|
|
|
|
|
|
|
|
|
|
* ``summary``: a phrase summarising what this API does. Start with a capital,
|
|
|
|
|
* ``summary``: a phrase summarising what this API does. Start with a capital,
|
|
|
|
|
end with a full-stop. Examples: "Sends an event."; "Searches the directory."
|
|
|
|
|
|
|
|
|
|
* ``description``: a longer description of the behaviour of this API, written
|
|
|
|
|
* ``description``: a longer description of the behaviour of this API, written
|
|
|
|
|
in complete sentences.
|
|
|
|
|
|
|
|
|
|
* ``operationId``: a camelCased unique identifier for this endpoint. This will
|
|
|
|
|
* ``operationId``: a camelCased unique identifier for this endpoint. This will
|
|
|
|
|
be used to automatically generate bindings for the endpoint.
|
|
|
|
|
|
|
|
|
|
* Parameter and property ``description``\s: a phrase summarising the behaviour
|
|
|
|
|
* Parameter and property ``description``\s: a phrase summarising the behaviour
|
|
|
|
|
of this parameter or property, optionally followed by sentences giving more
|
|
|
|
|
detailed explanations.
|
|
|
|
|
|
|
|
|
|