Документування API (Swagger/OpenAPI) для веб-додатку

Ви написали REST API, але фронтенд-розробники постійно плутають ендпоінти та формати запитів. Без єдиної специфікації кожен новий учасник витрачає до 8 годин на вивчення коду та ручне тестування. За статистикою, команди без специфікації витрачають на інтеграцію в 2–3 рази більше часу, а помилки через невідповідність документації та коду складають до 30% інцидентів. OpenAPI вирішує це — єдиний контракт, зрозумілий і людям, і інструментам. Ми створюємо API-документацію під ключ, щоб ви уникнули цих проблем.

OpenAPI (колишній Swagger) — стандарт опису REST API у форматі YAML або JSON, підтримуваний спільнотою OpenAPI Specification. Документація у OpenAPI-форматі дозволяє автоматично генерувати інтерактивний UI (Swagger UI, Redoc), клієнтські SDK та серверні заглушки. Це пришвидшує інтеграцію та знижує кількість помилок на 40–60%. Наприклад, в одному проєкті з 50 ендпоінтами ми скоротили час інтеграції з 3 днів до 4 годин завдяки автогенерації клієнта — економія 80% часу.

Чому OpenAPI критичний для API-документації?

Завдяки OpenAPI команди фронту і беку працюють за єдиним контрактом. Специфікація слугує джерелом правди: зміни спочатку вносяться в YAML, потім обговорюються. Це виключає ситуацію, коли документація розходиться з кодом. Крім того, OpenAPI дозволяє автоматично валідувати вхідні запити, що знижує навантаження на тестування. Команди, які використовують design-first підхід, інтегруються в 3 рази швидше порівняно з відсутністю специфікації. А валідація запитів за схемою виявляє до 95% проблем до продакшену.

OpenAPI 3.1 структура

---
openapi: 3.1.0
info:
  title: Articles API
  version: 1.0.0
  description: |
    REST API для керування статтями.
    ## Аутентифікація
    Bearer token у заголовку `Authorization: Bearer <token>`
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:3000/v1
    description: Development
paths:
  /articles:
    get:
      tags: [Articles]
      summary: Список статей
      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: Список статей
          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, example: "550e8400-e29b-41d4-a716-446655440000" }
        title: { type: string, maxLength: 200, example: "Заголовок статті" }
        status: { type: string, enum: [draft, published, archived] }
        createdAt: { type: string, format: date-time }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    Unauthorized:
      description: Не авторизовано
      content:
        application/json:
          schema: $ref: '#/components/schemas/ErrorResponse'

Code-first vs Design-first

Вибір підходу залежить від зрілості проекту. Порівняйте:

Приклад code-first в Laravel (PHP) через dedoc/scramble:

// Автоматично генерує OpenAPI з роутів та PHPDoc
composer require dedoc/scramble

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

Приклад code-first в Node.js через @fastify/swagger:

// Fastify + @fastify/swagger
fastify.register(fastifySwagger, {
  openapi: {
    info: {
      title: 'API',
      version: '1.0'
    }
  }
});
fastify.register(fastifySwaggerUi, {
  routePrefix: '/docs'
});
fastify.get('/articles', {
  schema: {
    querystring: {
      type: 'object',
      properties: {
        page: {
          type: 'integer'
        }
      }
    },
    response: {
      200: {
        $ref: 'ArticleList#'
      }
    }
  }
}, handler);

Що обрати: Swagger UI чи Redoc?

Можна використовувати обидва: Redoc для публічної документації, Swagger UI для розробників.

Як валідація запитів скорочує час розробки?

Валідація запитів за OpenAPI-схемою виявляє невідповідності на ранньому етапі. Middleware, наприклад express-openapi-validator, перевіряє кожен вхідний запит і повертає детальну помилку, якщо параметр невалідний. Це скорочує час налагодження інтеграції на 50% і дозволяє відловити 95% проблем до потрапляння в продакшен.

// Express + express-openapi-validator
app.use(OpenApiValidator.middleware({
  apiSpec: './openapi.yaml',
  validateRequests: true,
  validateResponses: true,
  // корисно в dev для перевірки відповідей сервера
}));

В одному проєкті клієнт забув додати обов'язковий заголовок Authorization. Middleware повернула HTTP 400 із зазначенням точного поля. Розробник виправив запит за хвилину, замість того щоб годину розбиратися з неявною помилкою.

Коли варто обрати design-first підхід?

Design-first підхід особливо корисний для нових продуктів, де контракт узгоджується до початку розробки. Він дозволяє командам фронту і беку розробляти паралельно, спираючись на єдину специфікацію. Ми рекомендуємо design-first, якщо ваш API буде використовуватися зовнішніми розробниками або якщо в проєкті беруть участь кілька незалежних команд. У таких випадках інвестиція в написання OpenAPI-специфікації окупається швидше — час інтеграції скорочується в 2–3 рази.

Процес роботи: від аналізу до деплою

1. Аналіз існуючого API (або проектування нового).
2. Написання OpenAPI-специфікації з описом усіх ендпоінтів, схем даних і безпеки.
3. Налаштування Swagger UI та/або Redoc для інтерактивного перегляду.
4. Інтеграція валідації запитів і відповідей за схемою.
5. Генерація клієнтських SDK на JavaScript, Python або PHP.
6. Навчання команди роботі з документацією та передача готового рішення.

Кожен етап супроводжується рев'ю та тестуванням. У результаті ви отримуєте живу документацію, яка завжди відповідає коду.

Строки та вартість

Типові витрати часу на створення OpenAPI-специфікації для API з 20–30 ендпоінтами — 2–4 дні. Налаштування Swagger UI, валідації та генерації SDK додає ще 1 день. Фінальна вартість розраховується індивідуально і залежить від складності схем бізнес-логіки. Ми гарантуємо акуратну специфікацію, зрозумілу і розробникам, і замовникам.

Замовте розробку OpenAPI-специфікації для вашого API. Отримайте консультацію з документування вашого API — зв'яжіться з нами, щоб оцінити проєкт.