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
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 clientValidate the spec
npx @redocly/cli lint openapi.yamlCommon 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.