Info Section
API Title
The API title specified by the info.title field MUST be present and a non-empty string.
The API title should be descriptive and reflect the purpose of the API.
API Description
The info.description field provides a short overview of the API and MUST be present and a non-empty string.
...
The API Description may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.
API Contact
The info.contact section provides contact information about the API, including: name, url, and email address.
...
In ONAP, the info.contact.email field MUST be set to "onap-discuss@lists.onap.org"
API License
The info.license section specifies the license name and url for the API.
...
In ONAP, the info.license.url field MUST be set to "http://www.apache.org/licenses/LICENSE-2.0"
API Version
The info.version field is used to provide the version of the application API.
...
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
Extension Fields
Within the info section, the following are extensions of the Swagger specification and SHALL be required for ONAP:
...
The x-component field is a string type filed that describes the ONAP component that primarily owns the API from a development perspective. For examples, SDC, MSO, SNIRO, etc., or the mS name.
The x-logo field SHOULD be set to: "x-logo": { "url": "../onap_logo.png", "backgroundColor": "#FFFFFF" }
Host
The host field must specify the host name serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. (e.g., serverRoot:54321)
Base Path
The basePath field describes base path, relative to the host, on which the API is served. The value MUST start with a leading slash (/). The base path MUST only contain the MAJOR version number to minimize changes in the URL for MINOR and PATCH releases.
For ONAP the basePath field MAY be in the form: "/"<projectName>"/"<apiName>"/v"<majorVersionNumber>
Path Extensions
Under the Path, the x-interface info extension shall be required. This extension contains two attributes:
...
last-mod-release - use release number or name (this should be consistent, choose either one); string type. This is the last release that the API was modified in.
Path Operations
Operation Id
The operationId field within a path operation MUST be present and non-empty.
...
For ONAP, it is recommended that the operationId field within a path operation be formed as: <objectName><operation>. (e.g., petsGet) using camelCase for word separation.
Operation Summary
The summary field within a path operation MUST be present and non-empty.
The summary field within a path operation should be short, descriptive and reflect the purpose of the operation. Please limit the summary to 5 to 10 words only, and no more than 120 characters.
Operation Description
The description field within a path operation MUST MAY be present and non-empty.
...
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 SHOULD be present and non-empty.
Operation Responses
Each Operation MUST have at least one successful (i.e. 2xx) response defined.
Each Operation should define a default response that covers responses not specifically defined for the Operation.
Models
Descriptions
Definition descriptions MUST SHOULD be present and non-empty string for each model property.
Examples
All Model Properties that are not $refs should have an example value specified.
Naming Conventions
URL Construction
URI structure http://[host]:[port]/api{component-name}/{service-name}]/v{version-number}/{resource}
The URI is comprised of a fixed base uri /api{component-name}/{service-name}]/v{version-number} and the resource path. Only major version number is used in the URI. For example: http://127.0.0.1:8080/nbi/api/petstorev4/v1/petsstatus/dogs
CRUD function names should not be used in URIs. Instead, CRUD actions should be represented by HTTP methods. Below is the proposed methodology to implement CRUD operations in a RESTful API.
...
Forward slash separator (/) must MUST be used to indicate a hierarchical relationship
...
Further Information may be found at: https://wiki.onap.org/display/DW/RESTful+API+Design+Specification
Pluralization of Resource names
Always use plurals in resource / node names to keep API URIs consistent across all operations.
Model Names
Model names should be simple, descriptive, and meaningful.
Model names should be in "upper camel case".
Property Names
Property names should be simple, meaningful, and descriptive with defined semantics.
...
Array types should have plural property names. All other property names should be singular.
HTTP response status codes
The API specification should describe the right HTTP status code to return the client.
...
"message": "Sorry, the requested resource does not exist",
"code": 34
}