Generate OpenAPI Specs From API Contract: A Guide

Alex Johnson

-Nov 16, 2025

Generate OpenAPI Specs From API Contract: A Guide

Generate OpenAPI/Swagger Specification from API Contract: A Guide

In today's API-driven world, having a well-defined and machine-readable API specification is crucial. This article outlines the process of generating an OpenAPI 3.0 specification from an authoritative API contract, which is essential for various tasks such as API testing, SDK generation, interactive documentation, and request/response validation.

Objective: Crafting a Machine-Readable OpenAPI 3.0 Specification

The primary objective is to transform the API contract into an OpenAPI 3.0 specification. This specification will serve as the single source of truth for describing the API's endpoints, data models, and behavior. The end result will be a docs/openapi.yaml file containing the complete API definition.

Context: API_CONTRACT.md as the Single Source of Truth

The API_CONTRACT.md file acts as the definitive source of information for the API. By generating an OpenAPI specification from this contract, you ensure consistency and accuracy across all API-related activities. This approach eliminates discrepancies and streamlines the development workflow.

Benefits of OpenAPI Specification

Enable API Testing Tools: Tools like Postman and Insomnia can leverage the OpenAPI specification to automate API testing, making it easier to verify functionality and identify issues.
Auto-Generate Client SDKs: The specification allows for the automatic generation of client SDKs in various programming languages (e.g., TypeScript, Swift), reducing the effort required to integrate the API into different applications.
Power Interactive Documentation: Swagger UI can use the OpenAPI specification to create interactive documentation, enabling developers to explore the API's endpoints, data models, and examples.
Validate Requests/Responses in Tests: The specification can be used to validate requests and responses in automated tests, ensuring that the API behaves as expected.

Acceptance Criteria: Ensuring a Complete and Accurate Specification

To ensure that the generated OpenAPI specification meets the required standards, the following acceptance criteria must be met:

OpenAPI 3.0 Spec Generated in docs/openapi.yaml: The specification file must be generated in the correct format and placed in the specified directory.
All v1 Endpoints Documented with Request/Response Schemas: Every endpoint in the v1 version of the API must be documented with detailed request and response schemas, including data types, validation rules, and examples.
All DTOs (WorkDTO, EditionDTO, AuthorDTO) Defined as Components: Data Transfer Objects (DTOs) such as WorkDTO, EditionDTO, and AuthorDTO must be defined as reusable components within the specification. This promotes consistency and simplifies the definition of endpoints that use these DTOs.
Error Codes and Responses Included: The specification must include definitions for all possible error codes and responses, providing developers with clear guidance on how to handle errors.
Rate Limiting Headers Documented: If the API employs rate limiting, the corresponding headers must be documented in the specification, informing developers about the limits and how to avoid exceeding them.
WebSocket Operations Documented (where supported by OpenAPI): If the API supports WebSocket operations, these must be documented in the specification, including the connection details, message formats, and event types.

Implementation Notes: Tools and Techniques for Generating the Specification

Several tools and techniques can be used to generate the OpenAPI specification from the API contract. Here are a few options:

openapi-typescript: This tool can generate TypeScript types from the OpenAPI specification, enabling type-safe API interactions in TypeScript projects.
swagger-jsdoc: This tool can generate the OpenAPI specification from JSDoc comments in the code. This approach can be useful for documenting APIs directly within the codebase.
Manual YAML Authoring: While it may be more time-consuming, manually authoring the OpenAPI specification in YAML provides the most control and accuracy. This approach is particularly suitable for complex APIs or when the API contract is not easily convertible using automated tools.

Steps for Manual YAML Authoring:

Install a YAML Editor: Choose a YAML editor that provides syntax highlighting, validation, and auto-completion. Popular options include VS Code with the YAML extension, Sublime Text with the YAML package, and online YAML editors like YAMLlint.
Create the openapi.yaml File: Create a new file named openapi.yaml in the docs/ directory. This file will contain the OpenAPI specification.
Define the OpenAPI Version and Info: Start by defining the OpenAPI version and basic information about the API, such as the title, description, and version number. For example:
```
openapi: 3.0.0
info:
  title: Bookstrack API
  description: API for managing books, editions, and authors.
  version: 1.0.0
```

Define the Servers: Specify the base URL(s) for the API. This allows clients to know where to send requests. For example:

servers:
  - url: 'https://api.bookstrack.com/v1'
    description: Production server
  - url: 'http://localhost:3000/v1'
    description: Development server

Define the Components: Define reusable components such as DTOs, schemas, and security schemes. This promotes consistency and simplifies the definition of endpoints. For example:

components:
  schemas:
    WorkDTO:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the work.
        title:
          type: string
          description: The title of the work.
    EditionDTO:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the edition.
        title:
          type: string
          description: The title of the edition.
        isbn:
          type: string
          description: The ISBN of the edition.
    AuthorDTO:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier for the author.
        name:
          type: string
          description: The name of the author.

Define the Paths: Define the API's endpoints, including the HTTP methods, request parameters, request body, and response schemas. For example:

paths:
  /works:
    get:
      summary: Get all works
      description: Retrieve a list of all works.
      responses:
        '200':
          description: A list of works.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkDTO'
    post:
      summary: Create a new work
      description: Create a new work.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkDTO'
      responses:
        '201':
          description: The newly created work.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkDTO'

Document Error Codes and Responses: Include definitions for all possible error codes and responses. For example:

      responses:
        '400':
          description: Bad request. The request was invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: A description of the error.
        '500':
          description: Internal server error. An unexpected error occurred on the server.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: A description of the error.

Document Rate Limiting Headers: If the API employs rate limiting, document the corresponding headers. For example:

      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
            description: The number of allowed requests in the current period.
        X-RateLimit-Remaining:
          schema:
            type: integer
            description: The number of remaining requests in the current period.
        X-RateLimit-Reset:
          schema:
            type: integer
            description: The number of seconds until the rate limit resets.

Validate the OpenAPI Specification: Use a tool like the Swagger Editor or the OpenAPI CLI to validate the OpenAPI specification and ensure that it is valid and well-formed. Fix any errors or warnings that are reported.
Test the API with the OpenAPI Specification: Use the OpenAPI specification to generate client SDKs or test the API with tools like Postman or Insomnia. Verify that the API behaves as expected and that the documentation is accurate.

Priority: Balancing Developer Experience and Integration Needs

The priority for generating the OpenAPI specification is Medium. While it is not a blocking issue for iOS integration, it is valuable for improving the developer experience. The specification will streamline API testing, SDK generation, and documentation, making it easier for developers to work with the API.

Related Resources: Leveraging Existing Documentation and Tools

API_CONTRACT.md: The source of truth for the API definition.
Swagger UI: Consider hosting Swagger UI at the /api/docs endpoint to provide interactive documentation for the API.

Estimate: Time Required for Generating the Specification

The estimated time required to generate the OpenAPI specification is 4-6 hours. This estimate includes the time needed to analyze the API contract, define the endpoints and data models, and validate the specification.

By following these steps, you can generate a comprehensive and accurate OpenAPI specification that will improve the developer experience and streamline the API development workflow. Remember, a well-defined API specification is the cornerstone of a successful API.

For more information on OpenAPI and Swagger, visit the Swagger website. This external resource can provide additional insights and best practices for creating and managing OpenAPI specifications.