OpenAPI Guidelines

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