Разработка API Reference документации

Разработка API Reference документации

API Reference — это исчерпывающее описание каждого endpoint, метода, параметра и ответа API. Это не инструкция «с чего начать» — это справочник, к которому разработчик возвращается при написании каждой интеграции. Неполный или устаревший Reference означает лишние вопросы в поддержку и ошибки при интеграции.

OpenAPI как основа

Современный стандарт для REST API — OpenAPI Specification 3.1 (OAS). Файл спецификации в YAML или JSON служит source of truth: из него генерируется и документация, и мок-сервер, и SDK на разных языках, и тесты. Писать спецификацию вручную или поддерживать её актуальность через аннотации в коде — зависит от размера команды.

Структура OpenAPI 3.1:

openapi: 3.1.0
info:
  title: Payments API
  version: 2.1.0
  description: |
    Управление платёжными транзакциями.
    Base URL: `https://api.example.com/v2`

paths:
  /payments:
    post:
      summary: Создать платёж
      tags: [Payments]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
            example:
              amount: 9900
              currency: "RUB"
              description: "Оплата заказа #12345"
      responses:
        '201':
          description: Платёж создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '422':
          $ref: '#/components/responses/ValidationError'

Автогенерация из кода

Laravel + Scramble — генерирует OpenAPI spec без единой аннотации, анализируя типы PHP, FormRequest классы и ресурсы:

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

FastAPI — OpenAPI генерируется автоматически из type hints и Pydantic моделей. Интерактивная документация доступна на /docs (Swagger UI) и /redoc из коробки.

NestJS — @nestjs/swagger с декораторами @ApiProperty, @ApiOperation генерирует полную спецификацию. При использовании mapped types (PartialType, PickType) схемы наследуются автоматически.

Express.js — swagger-jsdoc читает JSDoc комментарии над роутами:

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Получить пользователя
 *     parameters:
 *       - in: path
 *         name: id
 *         schema:
 *           type: string
 *           format: uuid
 *         required: true
 *     responses:
 *       200:
 *         description: Пользователь найден
 */
router.get('/users/:id', userController.getById);

Рендеринг документации

Scalar — рекомендуемый выбор для новых проектов: поддерживает OAS 3.1 полностью, имеет встраиваемую версию для Docusaurus, Express, FastAPI.

Примеры кода на нескольких языках

Автоматическая генерация примеров из OpenAPI спецификации — через openapi-snippet или встроенные возможности Scalar/Stoplight. Минимальный набор языков: curl, JavaScript (fetch), Python (requests), PHP (Guzzle).

Versioning и Changelog

При наличии нескольких версий API документация должна поддерживать переключение: /api/v1 vs /api/v2. В Docusaurus это реализуется через встроенный versioning. Каждая breaking change в API должна сопровождаться migration guide в том же PR, что вносит изменение.

Типичные сроки

Написание/доработка OpenAPI спецификации для существующего API (20–50 endpoints) — 3–5 дней. Настройка автогенерации из кода — 1–2 дня. Настройка Scalar/ReDoc с кастомным дизайном и деплоем — 1 день. Написание примеров кода и migration guides — 2–3 дня.