What Is OpenAPI (Swagger)?

OpenAPI is a standard specification format for describing a REST API's endpoints, request/response shapes, and authentication requirements in a machine-reada...

Published November 17, 2026

OpenAPI (formerly Swagger) is a standard, machine-readable format (YAML or JSON) for describing REST APIs: endpoints, parameters, responses and schemas. Tools generate documentation, client SDKs and tests from it.

The concept

The spec is the single source of truth. Swagger UI renders it as interactive docs where you can try calls; generators create client libraries and server stubs.

You can write the spec first (design-first) or generate it from code annotations (code-first).

One spec, many outputs

rendersgeneratesopenapi.yamlthe specSwagger UIdocsGeneratorsSDKs, mocks
Spec drives docs, SDKs and validation.

Practical examples

Minimal spec

openapi: 3.0.3
info: { title: Users API, version: 1.0.0 }
paths:
  /users/{id}:
    get:
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
components:
  schemas:
    User: { type: object, properties: { id: { type: integer }, name: { type: string } } }

Generate a client

npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o client

Validate the spec

npx @redocly/cli lint openapi.yaml

Common mistakes

  • Letting the spec drift from the real API.
  • Omitting error responses.
  • Not versioning the spec.

Key takeaways

  • Standard API description format.
  • Generates docs, SDKs, tests.
  • Keep it in sync with the code.

FAQ

Swagger vs OpenAPI?

OpenAPI is the specification; Swagger is the toolset (UI, editor, codegen).

Can it describe GraphQL?

No; GraphQL has its own schema language.

More HTTP articles