Розробка 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 дні.