OpenAPI (Swagger)

This content is for Backend. Switch to the latest version for up-to-date documentation.

OpenAPI is a standard format (JSON/YAML) for describing an HTTP API: endpoints, parameters, request/response shapes, and authentication.

It’s often shown with Swagger UI.

Where OpenAPI Is Used

API documentation portals
Generating client SDKs (frontend/mobile) from a single spec
Contract-first development between teams (backend/frontend)

Industry Examples (Companies)

GitHub: publishes an OpenAPI description for its REST API
Azure / Microsoft: heavy usage of API specs and generated SDKs across cloud services

Why Teams Like It

One source of truth for routes + payloads
Makes breaking changes easier to spot
Helps new developers explore APIs quickly

Tiny Example (YAML)

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        "200":
          description: OK
  /users/{id}:
    get:
      summary: Get one user
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK

Swagger vs OpenAPI

OpenAPI is the specification.
Swagger UI is a popular tool that renders an interactive docs website from an OpenAPI file.

References

Built with passion by Ngineer Lab