...
The API Description may include information about basic instructions (e.g., Getting Started) to users on how to use the API, such as host port, authentication, common error codes, test environment, etc., as well as links to additional resources (such as ONAP Use Cases), plus other details that would help other developers start using the API.
might want to The API Description should provide some basic instructions to users on how to use a Swagger viewer (e.g., Redoc, Swagger UI, etc.).
The API Description may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.
...
The info.version field is used to provide the version of the application API.
Note: Align URLs to include only the MAJOR version. For example, the base path MUST only contain the MAJOR version number.
In ONAP, the info.version field MUST be set to the fully-qualified version number of the Swagger file (ex: 1.4.18). Further information about versioning is ONAP may be found at: https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines
...
api-version - fully-qualified version number of the API (ex: 1.3.6); string type. This is the version of the API. This differs from the version in SG-2 abovein the Info filed. Components shall follow the Versioning Use Cases above to determine how to evolve API versions.
...
For ONAP, it is recommended that the operationId field within a path operation be formed as: <objectName>"_"<><operation>. (e.g., pets_get)petsGet) using camelCase for word separation.
Operation Summary
The summary field within a path operation MUST be present and non-empty.
...
The description field within a path operation may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.
The description field within a path operation may provide example calls or usages of the operation.
Operation Tags
The tags field within a path operation MUST be present and non-empty.
...
The tags field within a path operation is used to group operations logically into categories or topics, such as Account, Payments, Reports, Search, etc.
Operation Parameters
The description field within an operation parameter MUST be present and non-empty.
Operation Responses
Each Operation must MUST have at least one successful (i.e. 2xx) response defined.
Each Operation must should define a default response that covers responses not specifically defined for the Operation.
Models
Descriptions
Definition descriptions MUST be present and non-empty string for each model property.
Examples
All Model Properties that are not $refs should have an example value specified.
Local Definitions
The API specification should not have local definitions (i.e. only $refs are allowed)
That is, APIs should not have the definitions section (even if these local definitions are not used). Instead, schemas should be kept in domains and referenced using domain references.
A domain is a library of common components – such as parameters, responses and data models – that are used across multiple API definitions
Naming Conventions
URL Construction
...
Forward slash separator (/) must be used to indicate a hierarchical relationship
Use Prefer camelCase, but if necessary use Hyphens (-) instead of Underscores (_) if separation of words is needed in the URI
...
Property names should be simple, meaningful, and descriptive with defined semantics.
Property names MUST be camel-casedcamelCased, ascii strings.
The first character MUST be a letter.
...