OpenAPI Documents, Swagger UI & Editor

Swagger → OpenAPI

"Swagger" was the original name for the tooling; the specification itself is now formally the OpenAPI Specification (OAS). "Swagger" persists as the tooling brand (Swagger UI, Swagger Editor, Swagger Codegen) working with OpenAPI-formatted documents.

A Minimal OpenAPI Document

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      tags: [Users]
      summary: Get a user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/User' }
        '404':
          description: Not found
components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }

Path parameters ({id}) are explicitly typed/documented. $ref reuses a schema (User) across multiple endpoints without repeating its definition. Multiple response codes (200, 404) document more than just the happy path. tags (Users) group related endpoints for navigation. securitySchemes describe auth requirements so Swagger UI can offer a real "Authorize" button.

Swagger UI & Editor

Swagger UI renders an interactive docs page directly from the spec — browse endpoints, see schemas, and send real "try it out" test requests without Postman/curl. Swagger Editor gives real-time validation and preview while authoring the spec by hand.