Difference between revisions of "OpenAPI Guidelines"
(Created page with "OpenAPI developement guidelines for ETSI technical bodies and working groups.") |
|||
| (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 13:38, 20 September 2017
OpenAPI developement guidelines for ETSI technical bodies and working groups.
Splitting definitions in several files
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:<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
root |- ApiName.split.yaml |- ApiName.yaml |- definitions | - DataType.yaml |- examples | - DataTypeExample.yaml |- externalDocs |- index.yaml |- info |- index.yaml |- parameters |- index.yaml |- paths |- index.yaml