API Documentation (Swagger/OpenAPI) for Web Application

Documenting API (Swagger/OpenAPI) for Web Application

OpenAPI (formerly Swagger)—a standard for describing REST APIs in YAML or JSON format. Documentation in OpenAPI format allows automatic generation of interactive UI (Swagger UI, Redoc), client SDKs, and server stubs.

OpenAPI 3.1 Structure

openapi: 3.1.0
info:
  title: Articles API
  version: 1.0.0
  description: |
    REST API for managing articles.
    ## Authentication
    Bearer token in `Authorization: Bearer <token>` header

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:3000/v1
    description: Development

paths:
  /articles:
    get:
      tags: [Articles]
      summary: List of articles
      operationId: listArticles
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: status
          in: query
          schema: { type: string, enum: [draft, published, archived] }
      responses:
        '200':
          description: List of articles
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ArticleList' }
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []

components:
  schemas:
    Article:
      type: object
      required: [id, title, status, createdAt]
      properties:
        id: { type: string, format: uuid }
        title: { type: string, maxLength: 200 }
        status: { type: string, enum: [draft, published, archived] }
        createdAt: { type: string, format: date-time }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    Unauthorized:
      description: Not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

Code-First vs Design-First

Design-first: write OpenAPI YAML first, then implement. Ensures API-first approach, contract before development.

Code-first: annotations/decorators in code generate OpenAPI. More convenient for existing projects.

Laravel (PHP)—code-first via dedoc/scramble:

// Auto-generates OpenAPI from routes and PHPDoc
composer require dedoc/scramble

// In AppServiceProvider
Scramble::configure()
    ->withDocumentTransformer(function (OpenApi $openApi) {
        $openApi->secure(SecurityScheme::http('bearer'));
    });

Node.js—via tsoa or Fastify:

// Fastify + @fastify/swagger
fastify.register(fastifySwagger, {
  openapi: { info: { title: 'API', version: '1.0' } }
});

Tools and Viewers

• Swagger UI—interactive documentation, try-it-out requests
• Redoc—clean reference documentation
• Stoplight—visual API design editor
• Postman—import OpenAPI specs, test APIs

Timelines

Design-first OpenAPI documentation: 2–3 days. Code-first setup with auto-generation: 1–2 days. Full documentation with examples, authentication flows: 3–5 days.