# Спецификация из ответов (/ru/docs/specs/specs-from-traffic)

Запросы у вас часто появляются раньше спецификации: коллекция, которую кто-то импортировал, или вызовы, которые вы
пробовали, знакомясь с API. **Спецификация из ответов** превращает их в документ OpenAPI. Каждый запрос становится
операцией, описанной по последнему полученному на него ответу: путь и параметры, отправленное тело, а также ответ со
схемой JSON Schema его тела и примером. Добавляйте в уже существующую спецификацию, и она получит только то, чего ей
не хватало.

## Описание папки [#documenting-a-folder]

<Steps>
<Step>

Отправьте запросы, которые нужно описать, чтобы у каждого был ответ. В Alpenglow, например, отправьте запросы из папки
**Catalog**.

</Step>
<Step>

Щёлкните папку в боковой панели «Запросы» правой кнопкой и выберите **Описать в спецификации OpenAPI…**. Чтобы описать
всё рабочее пространство, выберите **+** › **Новая спецификация из ответов…** в боковой панели «Спецификации»,
**Из ответов…** на пустой странице «Спецификации» или **Новая спецификация из ответов…** в палитре команд.

</Step>
<Step>

В листе **Описать в спецификации OpenAPI** проверьте варианты:

| Вариант | Что значит |
| --- | --- |
| **Запросы** | **Всё рабочее пространство** или одна папка. Запросы её подпапок включаются. |
| **Спецификация** | **Новая спецификация** или спецификация рабочего пространства, в которую нужно добавить. Папка, которая уже следует спецификации, добавляет в неё. |
| **Название** | Название новой спецификации. Сначала это название папки или рабочего пространства. |
| **Связать «папка» со спецификацией** | По умолчанию включено. Запросы папки тогда следуют операциям, которыми стали, так что позднейшие изменения спецификации можно применять к ним. |

</Step>
<Step>

Нажмите **Описать**. Лист сообщит, что произошло, а **Открыть спецификацию** откроет результат.

</Step>
</Steps>

<Shot id="specs-from-responses" alt="Лист «Описать в спецификации OpenAPI» после описания папки Catalog: новые операции, не вошедшие запросы с причинами и кнопка «Открыть спецификацию»" />

## Что получится [#what-you-get]

В результате перечислено:

| Заголовок | Что значит |
| --- | --- |
| **Новые операции** | Операции, которых в спецификации не было, например `GET /products/{sku}`. |
| **Добавлен ответ** | Операции, которые в ней были и теперь описывают ещё один ответ, например `404`. |
| **Уже описаны** | Операции, которые она уже описывала так, как на них ответили. Ничего не изменилось. |
| **Не вошло** | Запросы, которые не были описаны, у каждого указана причина. |

Там же сказано, сколько запросов теперь следуют своим операциям и сколько ошибок линтер находит в результате, если
находит.

Что попадает в каждую операцию:

- **Путь** в форме OpenAPI: сегменты пути, пришедшие из переменных, становятся параметрами пути, описанными с
  отправленными значениями. Серверная часть URL в путь не входит.
- **Параметры запроса и заголовки**, которые задаёт запрос.
- **Тело запроса** и **ответ** со схемой JSON Schema, созданной по телу, и примером. Большие примеры опускаются, а
  схема остаётся; в длинных массивах пример сохраняет несколько элементов.
- **имя запроса** как сводка операции, а **его подпапка** как тег операции.
- **Авторизация запроса** как схема безопасности. Если в OpenAPI для неё нет схемы (OAuth 2 с типом предоставления
  device code), об этом сообщает примечание.

Секреты скрываются: секретные переменные и значения под ключами, похожими на секретные (токены, пароли, ключи),
выглядят в примерах как `••••••`.

## Добавление в существующую спецификацию [#adding-to-a-spec-you-have]

Выберите спецификацию в поле **Спецификация**. Echolot добавляет только то, чего не хватает: операции, ответы, схемы и
схемы безопасности, которые в ней ещё не названы. То, что в спецификации уже сказано, остаётся как написано.
Спецификации в Swagger 2.0 дополнять нельзя; только документы OpenAPI 3.

## Описание отдельных ответов из истории [#documenting-single-responses-from-history]

В [Истории](/docs/workspaces/history) щёлкните правой кнопкой HTTP-обмен, на который пришёл ответ, и выберите
**Добавить в спецификацию OpenAPI…**. Откроется тот же лист, но для одного этого ответа. Это удобно для ответа, который
вы увидели один раз, например ошибки.

## Что не вошло [#what-is-left-out]

- Запросы не HTTP (GraphQL, gRPC, WebSocket и прочие): в OpenAPI описываются только HTTP-запросы.
- Запросы, на которые ещё нет ответа: сначала отправьте их.
- Запросы, отправка которых завершилась ошибкой до получения ответа.
- Запросы в подпапке, которая следует собственной спецификации.

## Поддержание актуальности [#keep-it-current]

Когда папка следует спецификации, контрактом становится спецификация. Правьте её на странице «Спецификации» и
применяйте изменения к запросам через **Проверить изменения для «папка»…**. См.
[Запросы, которые следуют спецификации](/docs/specs#requests-that-follow-the-spec). Ответы спецификации можно также
отдать [моку](/docs/mocks), чтобы фронтенд мог работать с ней.

Агенты могут делать то же через инструмент `add_to_spec`, когда включён набор инструментов **Спецификации**: см.
[Агенты](/docs/ai/agents).