Skip to content

Latest commit

 

History

History
148 lines (120 loc) · 3.9 KB

api_documentation.md

File metadata and controls

148 lines (120 loc) · 3.9 KB

Best Practices for OpenAPI Documentation

Writing clear and comprehensive OpenAPI documentation is critical for developer adoption and API longevity. Below are best practices for versioning, model management, and endpoint documentation.

1. Model Management

Models (schemas) define the structure of request/response data. Consistency here reduces confusion.

Best Practices:

  • Leverage JSON Schema: Use OpenAPI's schema syntax to enforce validation.

    components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          example: "Jane Doe"

  • Reuse Components: Define reusable schemas, parameters, and responses under components to avoid duplication.

  • Provide Examples: Include sample data for clarity.

    examples:
  UserExample:
    value:
      id: 1
      name: "Jane Doe"

  • Document Enums and Constraints: Specify allowed values, formats, and limits.

    status:
  type: string
  enum: [active, inactive, pending]
  minLength: 4
  maxLength: 8

  • Version Models: Introduce new schema versions (e.g., UserV2) for breaking changes.

2. Endpoint Documentation

Clear endpoint docs help developers integrate quickly.

Best Practices:

  • Summarize and Describe:

    /users/{id}:
  get:
    summary: Get a user by ID
    description: Retrieves a single user's details, including name and contact info.

  • Document All Parameters:

    • Specify path, query, header, and body parameters.
    • Include examples and required flags.
    parameters:
  - in: path
    name: id
    required: true
    schema:
      type: integer
    example: 42

  • Cover All Responses:

    • Define HTTP status codes, especially errors (4xx/5xx).
    • Add examples for success and failure cases.
    responses:
  200:
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/User"
  404:
    description: User not found

  • Use Tags for Grouping: Organize endpoints by functionality (e.g., Users, Auth).

    tags:
  - name: Users
    description: Manage user accounts

  • Show Request/Response Examples:

    requestBody:
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/User"
      examples:
        UserExample:
          value:
            name: "Jane Doe"

  • Standardize Error Formats:

    components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

Where do I add documentation?

Good question, cowboy. We use serverless.yml to manage API declarations and deployments to APIGateway. So, it made sense to add a block for endpoint documentation.

All documentation is added in the docs folder. The yaml file follows the OpenAPI standards. Read about OpenAPI spec here openAPI

Next, edit serverless open serverless.yml in be-api-test serverless Under functions, see the documentation block documentation: ${file(./docs/api/documentation.yml):endpoints.api-endpoint}

Make sure you declare the documentation block for every endpoint.

Final Tips

  • Validate Your Spec: Use tools like Swagger Editor or Spectral to lint your OpenAPI file.
  • Automate Documentation: Generate interactive docs with Swagger UI or Redoc.
  • Keep It Consistent: Follow the same structure, naming conventions, and style across all endpoints.

Well-documented APIs reduce support overhead and empower developers to build faster. 📘🚀