API Documentation

Overview

API documentation describes how consumers interact with your service — endpoints, request/response schemas, authentication, error codes, and usage examples. It serves as the contract between frontend and backend teams, between microservices, and between your platform and third-party integrators. OpenAPI (REST) and AsyncAPI (event-driven) are the standard specification formats. In the full-lifecycle pipeline, @documentation-writer assembles API docs from the OpenAPI/AsyncAPI specs generated in Phase 4.

Key Concepts

API Documentation Types

Type	Format	Purpose	Tool
OpenAPI Spec	YAML/JSON	REST API contract	Swagger UI, Redoc
AsyncAPI Spec	YAML/JSON	Event/message contract	AsyncAPI Studio
API Reference	HTML/MD	Endpoint-by-endpoint guide	Generated from spec
API Guide	Markdown	Tutorials, workflows, patterns	Hand-written
Postman Collection	JSON	Interactive API examples	Postman

OpenAPI Essentials

openapi: '3.1.0'
info:
  title: Order Service API
  version: 1.0.0
  description: Manages order lifecycle
  
paths:
  /api/v1/orders:
    post:
      summary: Create a new order
      operationId: createOrder
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            example:
              customerId: "cust-123"
              items:
                - productId: "prod-456"
                  quantity: 2
      responses:
        '201':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

Documentation Quality Checklist

Criterion	Check
Every endpoint documented	All paths in OpenAPI spec
Request/response examples	Realistic JSON examples for each operation
Error codes documented	All 4xx/5xx with error schema
Authentication explained	How to obtain and pass tokens
Pagination documented	Query params, response metadata
Rate limits noted	Limits per tier, retry-after header
Versioning strategy	URL path (`/v1/`) or header based

Best Practices

Spec-first development — Write OpenAPI spec before implementing controllers
Include realistic examples — Not "string" but "user@example.com"
Document all error responses — 400, 401, 403, 404, 409, 422, 500 with schemas
Use $ref for reusable schemas — DRY principle for shared models
Version your API — URL path versioning (/v1/) for simplicity
Generate SDK from spec — Use openapi-generator for client libraries
Keep spec in version control — Same repo as the implementation
Auto-generate Swagger UI — springdoc-openapi for Spring Boot auto-configuration

Code Examples

✅ Good: Spring Boot OpenAPI Integration

// Springdoc auto-generates OpenAPI from controller annotations
@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Order lifecycle management")
public class OrderController {

    @Operation(
        summary = "Create a new order",
        description = "Creates an order and initiates payment processing"
    )
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "Order created",
            content = @Content(schema = @Schema(implementation = OrderResponse.class))),
        @ApiResponse(responseCode = "400", description = "Invalid request",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
        @ApiResponse(responseCode = "409", description = "Duplicate order",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
    })
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderResponse createOrder(
        @Valid @RequestBody CreateOrderRequest request
    ) {
        return orderService.createOrder(request);
    }
}

✅ Good: Error Response Schema

# Standard error response (RFC 7807 Problem Details)
components:
  schemas:
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          format: uri
          example: "/errors/validation-failed"
        title:
          type: string
          example: "Validation Failed"
        status:
          type: integer
          example: 400
        detail:
          type: string
          example: "Field 'email' must be a valid email address"
        instance:
          type: string
          format: uri
          example: "/api/v1/orders/12345"
        violations:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

❌ Bad: Underdocumented API

@PostMapping("/orders")
public Order create(@RequestBody Map<String, Object> body) {
    // No schema, no validation, no error docs
    // Consumer has to guess the request format
    return orderService.create(body);
}

Anti-Patterns

No spec at all — “Just look at the code” is not documentation
Stale spec — OpenAPI spec doesn’t match actual implementation
Missing error docs — Only 200 responses documented; consumers can’t handle errors
Generic examples — "string" instead of "user@example.com"
No authentication docs — Consumer can’t figure out how to authenticate
Implementation-coupled spec — Exposing internal field names or IDs

Testing Strategies

Spec validation — spectral lint openapi.yaml in CI
Contract testing — SpringCloudContract or Pact validates spec matches implementation
Documentation coverage — Assert every controller endpoint exists in spec
Link checking — Verify all documentation links resolve

API Documentation

API Documentation

Overview

Key Concepts