OpenAPI Guidelines
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