OpenAPI development guidelines: Difference between revisions

From MECwiki
Jump to: navigation, search
(Created page with "OpenAPI development guidelines for ETSI ISG MEC. More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Guidelines].")
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
OpenAPI development guidelines for ETSI ISG MEC.
OpenAPI development guidelines for ETSI MEC ISG API specifications.
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/OpenAPI_Guidelines Forge OpenAPI Guidelines].
More general recommendations can be found at [https://forge.etsi.org/wiki/index.php/Main_Page Forge OpenAPI Guidelines].
 
= How to review the latest versions =
 
<big>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 [https://forge.etsi.org/jenkins/view/all/job/MEC%20-%20Multi-access%20Edge%20Computing/ latest succesful builds].</big>
 
<big>[[ShortGuideToReviewInGerrit|A short guide to review in Gerrit]]</big>
 
If you are willing to contribute or if you want more information, contact [mailto:cti_support@etsi.org?subject=MEC%20openapis%20development: ETSI CTI]. ETSI CTI have also made a [https://www.youtube.com/watch?v=YXO0R61Dcg8 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 [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).
 
=== Root API files ===
 
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 detail, paths are required to start with:
<pre>
<apiRoot>/<apiName>/<apiVersion>
</pre>
 
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 ===
 
<pre>
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
</pre>
 
=== File names ===
 
The naming schema provided in the examples for the "Repository structure" above is followed.

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.