API Reference Documentation Development

API Reference Documentation Development

API Reference is comprehensive description of every endpoint, method, parameter, and response. It's not a "getting started" guide—it's a reference developers return to during every integration. Incomplete or outdated Reference means extra support questions and integration errors.

OpenAPI as foundation

Modern REST API standard is OpenAPI Specification 3.1 (OAS). Specification file in YAML or JSON serves as source of truth: documentation, mock server, SDK on different languages, and tests are all generated from it. Whether to write specification manually or maintain it via code annotations depends on team size.

OpenAPI 3.1 structure:

openapi: 3.1.0
info:
  title: Payments API
  version: 2.1.0
  description: |
    Payment transaction management.
    Base URL: `https://api.example.com/v2`

paths:
  /payments:
    post:
      summary: Create payment
      tags: [Payments]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
            example:
              amount: 9900
              currency: "RUB"
              description: "Order #12345 payment"
      responses:
        '201':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '422':
          $ref: '#/components/responses/ValidationError'

Auto-generation from code

Laravel + Scramble — generates OpenAPI spec without annotations by analyzing PHP types, FormRequest classes and resources:

composer require dedoc/scramble
php artisan scramble:export --path=docs/api.json

FastAPI — OpenAPI is auto-generated from type hints and Pydantic models. Interactive docs available at /docs (Swagger UI) and /redoc out of the box.

NestJS — @nestjs/swagger with @ApiProperty, @ApiOperation decorators generates full spec. With mapped types (PartialType, PickType) schemas are inherited automatically.

Express.js — swagger-jsdoc reads JSDoc comments above routes:

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get user
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: string
 *           format: uuid
 *         required: true
 *     responses:
 *       200:
 *         description: User found
 */
router.get('/users/:id', userController.getById);

Documentation rendering

Scalar is recommended for new projects: fully supports OAS 3.1, has embedded version for Docusaurus, Express, FastAPI.

Code examples in multiple languages

Auto-generate examples from OpenAPI spec via openapi-snippet or Scalar/Stoplight built-in features. Minimum language set: curl, JavaScript (fetch), Python (requests), PHP (Guzzle).

Versioning and Changelog

With multiple API versions, docs should support switching: /api/v1 vs /api/v2. In Docusaurus this is built-in versioning. Every breaking change should have migration guide in the same PR that introduces the change.

Typical timeline

Writing/updating OpenAPI spec for existing API (20–50 endpoints) — 3–5 days. Setting up auto-generation from code — 1–2 days. Setting up Scalar/ReDoc with custom styling and deploy — 1 day. Writing code examples and migration guides — 2–3 days.