Difference between revisions of "OpenAPI Guidelines"
| Line 3: | Line 3: | ||
= Splitting definitions in several files = | = Splitting definitions in several files = | ||
| − | The OpenAPI specification API definition splitting: <code>$ref<code> | + | The OpenAPI specification API definition splitting: <code>$ref</code> |
Already used in Location and RNI OpenAPI description examples below. | Already used in Location and RNI OpenAPI description examples below. | ||
| Line 27: | Line 27: | ||
</syntaxhighlight> | </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> | ||
Revision as of 13:30, 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