Какой уровень использования OpenAPI (Swagger) бывает на проектах?

Уровень использования OpenAPI/Swagger в проектах варьируется от простой документации до полноценного драйвера разработки. В моем опыте это выглядит так:

1. Уровень 1: Документация («Витрина API»). Спецификация пишется вручную или генерируется из аннотаций кода. Используется Swagger UI для интерактивной документации, доступной разработчикам фронтенда и клиентов.

2. Уровень 2: Контракт и кодогенерация. openapi.yaml становится единым источником истины. Мы использовали openapi-generator для автоматической генерации:

• Клиентских SDK на TypeScript для фронтенда.
• Серверных заглушек (stubs) на Spring, что ускоряло начало разработки бэкенда.

3. Уровень 3: Валидация и тестирование. Спецификация интегрируется в runtime:

• Валидация входящих/исходящих запросов через middleware (например, express-openapi-validator в Node.js).
• Контрактное тестирование (Pact) для проверки соответствия клиента и сервера спецификации.
• Интеграция в CI/CD: пайплайн падает, если сборка не генерирует актуальную спецификацию или если сгенерированный клиентский код не компилируется.

4. Уровень 4: Управление API как продуктом. Используются платформы вроде Apigee или Azure API Management для версионирования, мониторинга использования, установки лимитов и монетизации API. OpenAPI-спецификация — это конфигурационный файл для развертывания на таких платформах.

Пример фрагмента спецификации для генерации:

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'