OpenAPI Guidelines: Difference between revisions
(Created page with "OpenAPI developement guidelines for ETSI technical bodies and working groups.") |
No edit summary |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
OpenAPI developement guidelines for ETSI technical bodies and working groups. | OpenAPI developement guidelines for ETSI technical bodies and working groups. | ||
__TOC__ | |||
= Splitting definitions in several files = | |||
The OpenAPI specification API definition splitting: <code>$ref</code> | |||
Already used in Location and RNI OpenAPI description examples below. | |||
<syntaxhighlight lang="yaml"> | |||
get: | |||
description: Used to get a list of identifiers for zones authorized for use by the application. | |||
produces: | |||
- application/json | |||
responses: | |||
'200': | |||
description: Successful response to a query regarding the status of a zone | |||
schema: | |||
properties: | |||
zoneList: | |||
$ref: '#/definitions/ZoneList' | |||
</syntaxhighlight> | |||
Also offers the ability to place definitions and other code in a different file | |||
<syntaxhighlight lang="yaml"> | |||
get: | |||
$ref: ./Zones_Get.yaml | |||
</syntaxhighlight> | |||
The file “Zones_Get.yaml” contains everything after <code>get:<code> in the 1st extract. | |||
Example JSON (or yaml) can be provided for every resource, data type, etc. (again inline, or in separate files) | |||
<syntaxhighlight lang="yaml"> | |||
responses: | |||
200: | |||
description: Successful response to a query regarding the status of a zone | |||
schema: | |||
properties: | |||
zoneList: | |||
$ref: '#/definitions/ZoneList' | |||
examples: | |||
application/json: | |||
$ref: '../examples/ZoneList.json' | |||
</syntaxhighlight> | |||
== Proposed folder structure == | |||
<pre> | |||
root | |||
|- ApiName.split.yaml | |||
|- ApiName.yaml | |||
|- definitions | |||
| - DataType.yaml | |||
|- examples | |||
| - DataTypeExample.yaml | |||
|- externalDocs | |||
|- index.yaml | |||
|- info | |||
|- index.yaml | |||
|- parameters | |||
|- index.yaml | |||
|- paths | |||
|- index.yaml | |||
</pre> | |||
Latest revision as of 14:38, 20 September 2017
OpenAPI developement guidelines for ETSI technical bodies and working groups.
Splitting definitions in several files[edit | edit source]
The OpenAPI specification API definition splitting: $ref
Already used in Location and RNI OpenAPI description examples below.
<syntaxhighlight lang="yaml"> get: description: Used to get a list of identifiers for zones authorized for use by the application. produces: - application/json responses: '200': description: Successful response to a query regarding the status of a zone schema: properties: zoneList: $ref: '#/definitions/ZoneList' </syntaxhighlight>
Also offers the ability to place definitions and other code in a different file
<syntaxhighlight lang="yaml"> get: $ref: ./Zones_Get.yaml </syntaxhighlight>
The file “Zones_Get.yaml” contains everything after get: in the 1st extract.
Example JSON (or yaml) can be provided for every resource, data type, etc. (again inline, or in separate files)
<syntaxhighlight lang="yaml">
responses:
200:
description: Successful response to a query regarding the status of a zone
schema:
properties:
zoneList:
$ref: '#/definitions/ZoneList'
examples:
application/json:
$ref: '../examples/ZoneList.json'
</syntaxhighlight>
Proposed folder structure[edit | edit source]
root
|- ApiName.split.yaml
|- ApiName.yaml
|- definitions
| - DataType.yaml
|- examples
| - DataTypeExample.yaml
|- externalDocs
|- index.yaml
|- info
|- index.yaml
|- parameters
|- index.yaml
|- paths
|- index.yaml