API Standardization

SwaggerHub CLI provides the api:validate command to scan a specific API version:

swaggerhub api:validate OWNER/API_NAME/VERSION  - validate a specific version

swaggerhub api:validate OWNER/API_NAME  - validate the default version

The output is a list of standardization errors and warnings with line numbers:

line    severity        description

2:      CRITICAL        'info.license.name' required -> API license must be present and non-empty string
2:      CRITICAL        'info.license.url' required -> API license must be present and non-empty string
4:      WARNING      Semantic Versioning-Version must be MAJOR.MINOR.PATCH
15:     CRITICAL        'delete a user' does not comply with the rule -> Summary should start with upper case and end with a dot

The exit codes are:

• 0 - no errors or warnings
• 0 - warnings but no errors
• 1 - at least one CRITICAL error
• 2 - generic error (for example, the specified API was not found)

You can get the error list by sending a GET request to https://api.swaggerhub.com/apis/OWNER/API_NAME/VERSION/validation. For example:

curl -H "Authorization: YOUR_API_KEY" https://api.swaggerhub.com/apis/MyOrg/MyApi/1.0.0/validation

Sample response:

{
  "validation": [
    {
      "line": 2,
      "description": "'info.license.url' required -> API license must be present and non-empty string",
      "severity": "CRITICAL"
    },
    {
      "line": 4,
      "description": "Semantic Versioning-Version must be MAJOR.MINOR.PATCH",
      "severity": "WARNING"
    },
    ...
  ]
}

View API documentation

Each operation should have an operationId. Code generators use operationId as method names, so use IDs that would be appropriate as method names. For example, GET /pets/{id} could have operationId: getPetById. API documentation also uses operationId to generate permalinks to individual operations.

↑ Back to the rule list

Operation summary is a short explanation of what the operation does. Summaries are displayed next to the operation paths in the API docs, and are also used by code generators to produce the method documentation. A summary is an analog of the /** ... */ comments in Java or the <summary> element in C# XML comments.

↑ Back to the rule list

Use this rule to ensure that the operation summaries are proper sentences.

# Good
summary: Upload user profile image.

# Bad
summary: upload user profile image

↑ Back to the rule list

Use the description element to explain what this operation does and document any prerequisites and usage specifics. The description can be multiline and use Markdown for rich text representation. Detailed, up-to-date documentation helps developers use your API more effectively.

↑ Back to the rule list

Tags are used to group operations logically into categories, such as Account, Payments, Reports, Search, and so on. Use the tags element to specify an array of tags for an operation.

SwaggerHub uses tags in a few ways:

• API documentation displays the operations grouped by tags, which helps navigate and organize large APIs.

• Some code generators use tags to name the source code files and group operations into the same source file. For example, all operations with the payments tag may be generated in the PaymentsApi class file.

↑ Back to the rule list

Some code generators use tags to group operations into the same API class file. Using a single tag per operation ensures that the operations will not duplicate across several class files.

# Good
paths:
  /pet:
    post:
      summary: Add a new pet to the store.
      tags:
      - pet     # <-----

# Bad
paths:
  /pet:
    post:
      summary: Add a new pet to the store.
      tags:
      - pet       # <-----
      - store     # <-----

↑ Back to the rule list

Successful and error responses are an important part of an API definition. A successful response has an HTTP status code in the 2xx range, such as 200 OK or 201 Created. Each operation must have at least one successful response defined. In OpenAPI 3.0 definitions, the '2XX' keyword can be used to represent all successful responses.

↑ Back to the rule list

The default response covers possible HTTP response codes that are not defined individually for an operation. It is usually used to represent error responses without listing various 4xx codes individually. That said, it is a good idea to explicitly define any known errors, such as 401 Unauthorized or 404 Not Found.

responses:
  200:
    description: Successful operation
  401:
    description: Unauthorized
  default:    # <------
    description: Unexpected error

↑ Back to the rule list

The API title is specified by the info.title field. It appears at the top of API docs on SwaggerHub. Make sure the API title is descriptive and reflects the API purpose.

info:
  title: Acme Reports API   # <-------
  version: 1.0.0

↑ Back to the rule list

Use the info.description field to provide an overview of the API. The description can be multiline and use Markdown for rich text representation. For example, you can include information about authentication, rate limits, pagination, filtering, date and time formats, common error codes, links to additional resources (such as blog posts or external examples), and any other details that would help other developers start using your API.

info:
  title: Acme Reports API
  version: 1.0.0
  description: >-
    Use the Acme Reports API to create and schedule a variety of reports from your Acme data.
    Reports can be daily, weekly, monthly and quarterly.
    
    ## Authentication
    
    ...

↑ Back to the rule list

The API license lets the potential API consumers know how they are allowed to use your API. Use the info.license section to specify the license name and url. If you want an open-source license, visit https://choosealicense.com and https://opensource.org/licenses to find the most appropriate license for your needs.

info:
  title: Acme Reports API
  version: 1.0.0
  license:      # <-------
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

↑ Back to the rule list

This rule requires the info.contact.email field in API definitions. For public APIs, you can provide the email address of your support or API team. For internal APIs, provide the email of the responsible team or developer.

Note: While this rule requires just info.contact.email, it is a good idea to also provide info.contact.url (for example, a link to your support portal or your Slack channel) to give your API consumers multiple options to get in touch.

info:
  title: Acme Reports API
  version: 1.0.0
  contact:
    name: Acme Support
    email: support@example.com    # <-------
    url: https://support.example.com

↑ Back to the rule list

This rule requires that all properties that are not $refs have an example value specified. SwaggerHub uses property examples to display sample requests and responses in the API docs and also to generate mock responses. Use meaningful example values to help your API consumers understand what the actual data will look like.

definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
        example: 1    # <-------
      username:
        type: string
        example: demo-user  # <-------

Note that array properties require that an array-level example should be compliant:

# Good
definitions:
  Product:
    type: object
    properties:
      categories:
        type: array
          items:
            type: string
        example:    # <------- Array example is on the same level as "type: array"
          - clothes
          - accessories

# Bad - no array-level example (item example is not enough)
definitions:
  Product:
    type: object
    properties:
      categories:
        type: array
        items:
          type: string
          example: clothes

↑ Back to the rule list

To comply with this rule, APIs must 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.

Good:

      responses:
        200:
          description: A single inventory item
          schema:
            $ref: 'https://api.swaggerhub.com/domains/acme-org/common-models/1.0#/definitions/InventoryItem'

Bad:

      responses:
        200:
          description: A single inventory item
          schema:
            $ref: '#/definitions/InventoryItem'

definitions:
  InventoryItem:
    type: object
    ...

Note that this rule still allows inline schemas such as

      responses:
        200:
          description: An array of strings
          schema:
            type: array   # <-----
            items:
              type: string

↑ Back to the rule list