OpenAPI development guidelines: Difference between revisions

From MECwiki
Jump to: navigation, search
No edit summary
Line 14: Line 14:
== General guidelines ==
== General guidelines ==


MEC APIs are currently described using the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI 2.0 specification]. Members of the ETSI MEC ISG can view a tutorial [https://docbox.etsi.org/ISG/MEC/05-CONTRIBUTIONS/2017//MEC(17)000541_MEC023_Creating_a_OpenAPI_spec_compliant_API_description.pptx presentation]. That can be made available outside the ISG on request.
MEC APIs are currently described using the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md OpenAPI 2.0 specification]. Members of the ETSI MEC ISG can view a tutorial [https://docbox.etsi.org/ISG/MEC/05-CONTRIBUTIONS/2017//MEC(17)000541_MEC023_Creating_a_OpenAPI_spec_compliant_API_description.pptx 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 [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md 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 [https://github.com/swagger-api/swagger-codegen swagger-codegen], which is still in development (reference 3.0.0_enhancements branch).
A migration to the latest version of the [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md 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 [https://github.com/swagger-api/swagger-codegen swagger-codegen], which is still in development (reference 3.0.0_enhancements branch).
Line 20: Line 20:
=== Root API files ===
=== Root API files ===


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


In details, paths are required to start with:
In detail, paths are required to start with:
<pre>
<pre>
<apiRoot>/<apiName>/<apiVersion>
<apiRoot>/<apiName>/<apiVersion>
Line 30: Line 30:


=== Definitions ===
=== 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.
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 ===
=== 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.
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 ==
== Branching strategy ==

Revision as of 22:25, 11 December 2017

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

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. 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.