[ADP-751] New OpenAPI document

Guidance

OpenAPI Version

• MUST use OpenAPI 3.1.0 or later

  openapi: 3.1.0

• MUST use YAML format for better readability and ease of splitting

  • JSON format results in deeply nested objects which are difficult to read and maintain

• MUST move all response schemas into the components section

  • See ADP-758: Use of $ref in OpenAPI for details

• MUST include the following metadata in the info section:

  • title: Name of the API

  • description: Brief overview of the API's purpose

  • version: API version following ADP-24: Versioning Mechanism

  • contact: Information for API support (see ADP-759: OpenAPI Contact Info)

    Example:

    info:
      title: User Management API
      description: API for managing user accounts and profiles
      version: 1.0.0
      contact:
        name: API Support Team
        url: https://example.com/support
        email: api-support@example.com

• SHOULD define security schemes in the components section

• MUST apply appropriate security requirements to operations or the entire API

  Example:

  components:
    securitySchemes:
      bearerAuth:
        type: http
        scheme: bearer
        bearerFormat: JWT
  
  security:
    - bearerAuth: []

• SHOULD use tags to group related operations

• MUST provide descriptions for all tags

  Example:

  tags:
    - name: users
      description: User management operations
    - name: auth
      description: Authentication and authorization operations

• MUST use kebab-case for path segments

• MUST use camelCase for query parameters and operation IDs

• SHOULD provide a summary and description for each operation

• MUST use appropriate HTTP methods for operations (see ADP-110: HTTP Methods)

  Example:

  paths:
    /users/{userId}:
      get:
        summary: Get user details
        description: Retrieves detailed information about a specific user
        operationId: getUserDetails
        tags:
          - users
        parameters:
          - name: userId
            in: path
            required: true
            schema:
              type: string
        responses:
          '200':
            description: Successful response
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/User'

• SHOULD provide examples for request bodies and responses (see ADP-756: OpenAPI Provide Examples)

• MUST define common error responses in the components section

• SHOULD use standard HTTP status codes (see ADP-138: HTTP Status Code)

• MUST follow the problem details format for error responses (see ADP-401: HTTP Problem Basics)

• SHOULD define webhooks if the API supports them (see ADP-760: OpenAPI Webhooks)

• SHOULD verson control your OpenAPI document.

• DRAFT Updates to an API definition MUST require a code review and SHOULD be contingent on overall architectural review for service updates.

Related ADPs

• ADP-24: Versioning Mechanism
• ADP-41: API Versioning
• ADP-110: HTTP Methods
• ADP-138: HTTP Status Code
• ADP-401: HTTP Problem Basics
• ADP-753: OpenAPI x-rate-limit
• ADP-756: OpenAPI Provide Examples
• ADP-758: OpenAPI $ref
• ADP-759: OpenAPI Contact Info
• ADP-760: OpenAPI Webhooks

References

• OpenAPI Specification
• OpenAPI Best Practices
• IBM API Handbook

Changelog

• 2024.10.17 add version control