OpenAPI

This page provides a comprehensive set of guidelines and conventions to help developers maintain consistent and high-quality OpenAPI specifications.

Development Environment

• Install the OpenAPI (Swagger) Editor extension for IDEs to support OpenAPI development.
• Use Elements to visualize the OpenAPI specification.
• Use Spectral to lint the OpenAPI specification.

Naming

• Use snake_case for all directories and file names.

  /request-bodies
  request-bodies.yml
  post-create-user.yml
  

  /request_bodies
  request_bodies.yml
  post_create_user.yml
  

• The file name must match the resource’s name.

  Endpoint: /registrations
  File: paths/registrations/create_new_user.yml
  
  Endpoint: /oauth/token
  File: paths/oauth/login_with_email.yml
  
  Endpoint: /surveys/{id}
  File: paths/surveys/get_a_survey.yml
  
  Endpoint: /registrations
  File: examples/register_new_account.json
  
  Endpoint: /oauth/token
  File: examples/login_with_email.json
  

  Endpoint: /registrations
  File: paths/registrations.yml
  
  Endpoint: /oauth/token
  File: paths/oauth/token.yml
  
  Endpoint: /surveys/{id}
  File: paths/surveys_id.yml
  
  Endpoint: /registrations
  File: examples/registrations.json
  
  Endpoint: /oauth/token
  File: examples/oauth/token.json
  

• When a resource supports multiple operations, create a sub-directory named after the resource and a file named after each operation.

  Endpoint: GET /surveys
  File: paths/get_surveys.yml
  
  Endpoint: POST /surveys
  File: paths/creat_new_survey.yml
  

  Endpoint: GET /surveys
  File: paths/surveys/get.yml
  
  Endpoint: POST /surveys
  File: paths/surveys/post.yml
  

Folder Structure

The following directory structure should be followed to organize efficiently all OpenAPI documentation files:

└── codebase-root
    ├── ... # Other directories and files
    └── docs
        └── openapi
            ├── examples
            ├── paths
            ├── request_bodies
            ├── responses
            ├── schemas
            │   ├── requests
            │   ├── responses
            │   └── shared
            ├── openapi.yml
            ├── request_bodies.yml
            ├── responses.yml
            └── schemas.yml

Examples

• Contains all the examples for endpoints.

  examples
  ├── oauth
  │   └── token.json
  ├── surveys.json
  └── ...
  

• Contains only JSON files.

  examples
  ├── oauth
  │   └── token.yml
  └── users
      └── get.yml
  

  examples
  ├── oauth
  │   └── token.json
  └── users
      └── get.json
  

Paths

• Contains all the definitions of endpoints, including operations (HTTP methods), security, request body, responses, etc. Inside this folder, there should be sub-folders to group-related endpoints under common resources (e.g., oauth, users, health, etc…).

  paths
  ├── oauth
  │   ├── revoke.yml
  │   └── token.yml
  ├── users
  │   ├── get.yml
  │   └── post.yml
  ├── users.yml
  └── ...
  

• With an endpoint that has multiple operations, use $ref and create a separate file for each operation.

  # openapi.yml
  paths:
    /users:
      $ref: "paths/users.yml"
  
  # paths/users.yml
  /users:
    get:
      $ref: "users/get.yml"
    post:
      $ref: "users/post.yml"
  

Request Bodies

• Contains all shared request bodies for different endpoints.

  request_bodies
  ├── user.yml
  └── ...
  

• All the shared request bodies must be mentioned and referenced in the request_bodies.yml file in the openapi folder.

  # request_bodies.yml
  request_bodies_user:
    $ref: "request_bodies/user.yml"
  
  ...
  

Responses

• Contains all shared responses for different endpoints.

  responses
  ├── default_error.yml
  └── ...
  

• All the shared responses must be mentioned and referenced in the responses.yml file in the openapi folder.

  # responses.yml
  responses_default_error:
    $ref: "responses/default_error.yml"
  
  ...
  

Schemas

• Contains all shared schemas for different endpoints. Inside this folder, there are 3 sub-folders to group schemas by their types:

  • requests: contains all schemas for request bodies.
  • responses: contains all schemas for responses.
  • shared: contains all shared schemas for both request and response bodies.

  schemas
  ├── requests
  │   ├── oauth
  │   │   └── revoke.yml
  │   └── registrations.yml
  ├── responses
  │   ├── oauth
  │   │   └── token.yml
  │   └── surveys.yml
  └── shared
      ├── error.yml
      ├── survey.yml
      └── token.yml
  

• All the shared schemas must be mentioned and referenced in the schemas.yml file in the openapi folder.

  # schemas.yml
  #### REQUESTS ####
  
  requests_oauth_revoke:
    $ref: "schemas/requests/oauth/revoke.yml"
  
  requests_registrations:
    $ref: "schemas/requests/registrations.yml"
  
  #### RESPONSES ####
  
  responses_oauth_token:
    $ref: "schemas/responses/oauth/token.yml"
  
  responses_surveys:
    $ref: "schemas/responses/surveys.yml"
  
  #### REUSABLE SCHEMAS ####
  
  error:
    $ref: "schemas/shared/error.yml"
  
  token:
    $ref: "schemas/shared/token.yml"
  
  survey:
    $ref: "schemas/shared/survey.yml"
  
  ...
  

OpenAPI Specification File

• Contains the main OpenAPI specification file - the main entry point for the OpenAPI documentation.

• Separate the OpenAPI specification (openapi.yml) into multiple files to make it more readable and maintainable. Do NOT put everything in one.

  # openapi.yml
  components:
    schemas:
      $ref: "schemas.yml"
    requestBodies:
      $ref: "request_bodies.yml"
    responses:
      $ref: "responses.yml"
  
  paths:
    /registrations:
      $ref: "paths/registrations.yml"
  
    /oauth/token:
      $ref: "paths/oauth/token.yml"
  
    /oauth/revoke:
      $ref: "paths/oauth/revoke.yml"
  
    /surveys:
      $ref: "paths/surveys.yml"
  

• Use tags to group endpoints and operations.

  # openapi.yml
  tags:
  - name: Authentication
    description: Authentication APIs
  - name: Account
    description: Account APIs
  - name: Surveys
    description: Survey APIs
  
  # paths/oauth/token.yml
  post:
    tags:
      - Authentication
    ...
  
  # paths/registrations.yml
  post:
    tags:
      - Account
    ...
  
  # paths/surveys.yml
  get:
    tags:
      - Surveys
    ...
  

• Use components to define reusable schemas, request bodies, and responses.

  # openapi.yml
  components:
    schemas:
      $ref: "schemas.yml"
    requestBodies:
      $ref: "request_bodies.yml"
    responses:
      $ref: "responses.yml"
  
  # schemas.yml
  error:
    $ref: "schemas/shared/error.yml"
  
  token:
    $ref: "schemas/shared/token.yml"
  
  survey:
    $ref: "schemas/shared/survey.yml"
  
  # request_bodies.yml
  requests_user:
    $ref: "request_bodies/requests_user.yml"
  
  # responses.yml
  responses_default_error:
    $ref: "responses/default_error.yml"
  

In Practice

The team applies OpenAPI for API documentation in the Nimble Survey Web Project, which is used for internal certifications and external code challenges.

Nimble Survey Web Project - OpenAPI Documentation