Что именно подробно описывается в OpenAPI-документации?

В OpenAPI спецификации описывается REST API сервиса, включая:

• Эндпоинты (пути) с методами HTTP (GET, POST, PUT, DELETE и др.)
• Параметры запросов (query, path, header, cookie)
• Тела запросов и ответов с описанием структуры (схемы данных)
• Коды ответов и их описание
• Типы данных и форматы (например, string, integer, date-time)
• Безопасность (авторизация, аутентификация)
• Информацию о сервере (URL, описание)

Пример:

paths:
  /users/{id}:
    get:
      summary: Получить пользователя по ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Таким образом, OpenAPI спецификация служит формальным контрактом между клиентом и сервером, позволяя генерировать документацию, клиентские SDK и тесты.