OpenAPI development guidelines

OpenAPI development guidelines for ETSI MEC ISG API specifications. More general recommendations can be found at Forge OpenAPI Gudelines.

How to review the latest versions

If you are interested to access and download the raw YAML files built for each interface (currently only MEC-012 is built in this manner, the other interfaces will follow) visit latest succesful builds.

A short guide to review in Gerrit

If you are willing to contribute or if you want more information, contact ETSI CTI.

API development

General guidelines

MEC APIs are currently described using the OpenAPI 2.0 specification. Click here to find the official reference.

A migration to the OpenAPI 3.0 specification is being actively pursued within the ISG. However, it is desirable that auto-generation of client and server stubs are supported through swagger-codegen, which is still in development.

Root API files

Since the specification requires the apiVersion be after apiName in the resource path, each interface will have a separate OpenAPI root file.

In details, paths are required to start with:

<apiRoot>/<apiName>/<apiVersion>

the only way to model this with OAS is using separate files for each interface. This will also help readability and clarity.

Definitions

Definitions are currently not shared across API descriptions and there is no cross referencing. This is also the case in the group specifications themselves.

Resources

It's encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the complete description file is provided for several APIs.

Branching strategy

• Within the repository there will be a branch for each active version of the interfaces. A version is active if it is still under maintenance in the WG.
• Git tags will be used to label a commit on a branch with a specific revision of the deliberable.

Folder structure and file names

Repository structure

repository_root                     i.e. MEC
|- Group Specification (GS) x       e.g. MEC.GS-011
   |- Readme.md                     General API information
   |- APIx.json                     Auto-generated JSON
   |- APIx.yaml                     Main OAS file (auto-generated using the APIx.split.yaml file: multi-file-swagger Mp1.split.yaml > Mp1.json), e.g. Mp1.yaml
   |- APIx.split.yaml               Definition file split into its component parts, to bring it together use [https://github.com/mohsen1/multi-file-swagger-example multi-file-swagger]
      |- definitions
         | - DataType1.yaml         e.g. CurrentTime.yaml
         | - DataType2.yaml
      |- examples                   Example responses
         | - Example1.yaml          e.g. ServiceInfo.yaml
         | - Example2.yaml
      |- externalDocs               Links to external docs, i.e. the GS
         | - index.yaml
      |- info                       General info regarding API, e.g. Copyright
         | - index.yaml
      |- parameters                 API Body/Query/Path Parameters
         | - Parameter1.yaml        e.g. Body.DnsRule.yaml
         | - Parameter2.yaml        e.g. Path.DnsRuleId.yaml
      |- paths                      Paths associated with the API
         | - PathA.yaml             High level path, e.g. Services.yaml
         | - PathA.{method}.yaml    Lower level path, e.g. Services.GET.yaml
|- Group Specification y
   |- ...
|- Group Specification z
   |- ...
|- Readme.md
|- LICENSE

File names

The naming schema provided in the examples for the "Repository structure" above is followed.