What is OpenAPI

OpenAPI (formerly Swagger) is a specification for describing REST APIs in a machine-readable YAML or JSON document. It defines endpoints, request/response bodies, parameters, authentication methods, and error formats.

How it works

An OpenAPI document lists every endpoint in the API, its HTTP method, parameters, request body schema, response schemas, and authentication requirements. Tools read this document to generate interactive documentation (Swagger UI, Redoc), client SDKs (openapi-generator), server stubs, and request validators.

paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: User found

Why it matters

OpenAPI makes APIs self-documenting. Instead of maintaining separate documentation that drifts from the implementation, the spec is the documentation. Code generators ensure clients match the API contract. Validators catch request/response mismatches at development time. The OpenAPI ecosystem (editors, validators, mock servers, test generators) makes it the standard for REST API description.

See How REST Works for the API design patterns that OpenAPI documents describe.