OpenAPI development guidelines
OpenAPI Specification (OAS) 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 has also made a YouTube tutorial available (based on NFV) that provides guidance on how to contribute for MEC.
API development
General guidelines
As of January 2021, OAS representations have been updated to reflect the latest released versions of their corresponding GS (e.g. v2.1.x); the representations follow OpenAPI 3.0 specification language.
The following figure provides a high level overview of the OAS creation and usage.
As shown on the figure, OAS YAML file is used in 3 different contexts:
- To accurately reflect the GS API as released by ETSI MEC ISG
- To provide graphical UI documentation as an input to SwaggerUI JS Application
- To provide out-of-the-box API client library/package or server stub as an input to code generation tools
As such, when developing or updating the OAS YAML representations, the 3 usage described above should be considered.
The following sections provide guidelines on how to develop and validate OAS represnetaions.
OAS YAML Generation
Initial OAS generation involves using the ETSI maintained doc2oas tool; the figure below shows the steps involved in using this tool.
The following figure outlines doc2oas usage.
Step 1 - Create MEC-XYZ_config.yaml file
- this file contains all external types not defined in the GS in (OAS language)
- existing config files can be used as a template, types can be re-used from existing config files
- to quickly identify external types, Step2 can be performed with an empty config file - the resulting yaml file will show all unresolved types in the Swagger Editor
Step 2 - Use the doc2oas.sh script to generate MEC-XYZ.yaml
- the new specification must first be added to
doc2oas.shscript
Step 3 - Add endpoints as per the GS specification
- follow the model from existing specifications
- the end result should not show any error in Swagger Editor
OAS YAML Validation
Once the YAML file is available, the following validation steps should be performed to verify the validity in the different usage contexts
Level 1 Validation - OAS syntax
| Validation Tool | Validation Criteria |
|---|---|
| Swagger-Editor | - No remaining warning or errors when opening OAS YAML |
| Swagger-CLI | - Part of CI validation done via Jenkins in the repository
- Swagger-CLI reports no error/warnings - |
| Speccy | - Part of CI validation done via Jenkins in the repository
- Speccy reports no error/warnings - |
Level 2 Validation - Swagger UI
| Validation Tool | Validation Criteria |
|---|---|
| Swagger-UI | - No error when viewing the file via Swagger UI
- Thorough visual inspection of endpoints and data model |
Level 3 Validation - Code Generation
| Validation Tool | Validation Criteria |
|---|---|
| swagger-codegen-cli-v3 | - From CLI tool: generate client API library/package and server stub for Java and Golang
- Code generation succeeds - Extra: execute server stub without crash - Example Golang Server & Client
|
Proto3 Generation & Validation
Some API representations include a Protobuf representation along with the OAS3 representation; this representation is generated using the tool Open API Generator
Proto3 Generation
| Generation Tool | Generation Criteria |
|---|---|
| openapi-generator-cli-5.0.0-beta2 | - From CLI: generate Proto3 representation
- Proto3 generation succeeds - - Full inspection of the generated Proto3 is mandatory - At the time of writing, some Proto3 generated files needs to be touched manually: enumerations, structures containing allOf, oneOf, anyOf |
Proto3 Validation
| Validation Tool | Validation Criteria |
|---|---|
| protoc | - From CLI: generate source code from Proto3 representation
- Code generation succeeds - Sometimes, when generating code, it may be necessary to include the file empty.proto Example generate Go and Java mkdir go java protoc --go_out=go --java_out=java services/* protoc --go_out=go --java_out=java models/* |
Branching strategy
Development follows a simplified version of the popular GitFlow
master- released version of the OAS representationdevelop- final versions of OAS representations development, before they are approved to be merged on masterfeature branch- work branch, the final result should be merged on develop
For example, work performed by a Specialist Task Force (stf123)
- STF - From
develop, create astf123feature branch - STF - Once work is completed & validation pass, merge the
stf123todevelop - STF - Create a Merge Request from
developtomaster - SC - A member from the STF Steering Committee will perform the final merge
- SC - Apply a label corresponding the the GS version
Folder structure and file names
Repository structure
repository_root i.e. MEC ├── LICENSE ├── proto3 Protobuf representation generated from OAS yaml │ ├── models Protobuf models │ ├── README.md Protobuf general info │ └── services Protobuf services ├── README.md General API information ├── MEC-XYZ.json Auto-generated JSON (From Swagger Editor -> Save As json) └── MEC-XYZ.yaml Definition flat file used by Swagger-UI, Swagger-Editor, Swagger-CodeGen, etc.
NOTE: Naming of of the JSON and YAML files is generally chosen by the DECODE group and does not necessarily follow the pattern outlined above.