OpenAPI development guidelines

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

Latest versions

Latest versions of the OAS representations are available in their respective repositories (here)

Latest CI test results of the OAS representations are available here

Contributing

If you are willing to contribute or if you want more information, contact ETSI CTI. ETSI CTI have also made a YouTube tutorial available, which although based on NFV rather than MEC provides a valuable overall guide.

API development

General guidelines

MEC APIs are currently described using the OpenAPI 2.0 specification. Members of the ETSI MEC ISG can view a tutorial presentation on creating a OpenAPI based description using the MEC-011 Mp1 API as the basis. That can be made available outside the ISG on request.

A migration to the latest version of 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 (reference 3.0.0_enhancements branch).

Root API files

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

In detail, 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 is encouraged to create a separate file for each resource (as is the case for Mp1 and Location), although only the overall description file is provided for most 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.