Ты прямо в OpenAPI спецификации описываешь?

Да, OpenAPI спецификация позволяет описывать API прямо в формате YAML или JSON, где подробно указываются пути, методы, параметры, схемы данных и ответы. Это удобный способ документировать и стандартизировать API, а также генерировать клиентский код и тесты. Например, можно описать эндпоинт так:

paths:
  /users:
    get:
      summary: Получить список пользователей
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'