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

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

OpenAPI (формально Swagger)—стандарт описання REST API у форматі YAML або JSON. Документація в OpenAPI-форматі дозволяє автоматично генерувати інтерактивний UI (Swagger UI, Redoc), клієнтські SDK та серверні заглушки.

Структура 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 }
        title: { type: string, maxLength: 200 }
        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 проти Design-First

Design-first: спочатку пишеться OpenAPI YAML, потім реалізація. Забезпечує API-first підхід, контракт до розробки.

Code-first: анотації/декоратори в коді генерують OpenAPI. Зручніше для існуючих проектів.

Laravel (PHP)—code-first через dedoc/scramble:

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

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

Node.js—через tsoa або Fastify:

// Fastify + @fastify/swagger
fastify.register(fastifySwagger, {
  openapi: { info: { title: 'API', version: '1.0' } }
});

Інструменти та переглядачі

• Swagger UI—інтерактивна документація, спробувати запити
• Redoc—чиста довідкова документація
• Stoplight—редактор візуального дизайну API
• Postman—імпортувати OpenAPI специфікації, тестувати API

Терміни

Design-first OpenAPI документація: 2–3 дні. Code-first налаштування з автогенерацією: 1–2 дні. Повна документація з прикладами, потоками аутентифікації: 3–5 днів.