OpenAPI (Swagger)

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

• OpenAPI Specification
• Swagger UI