# Спецификации (/ru/docs/specs)

Страница «Спецификации» — это место, где вы проектируете и храните контракт API: документы OpenAPI (OpenAPI 3.0 и 3.1 и
Swagger 2.0) и файлы `.proto` сервисов gRPC. Echolot проверяет спецификацию по мере правки, превращает её в запросы,
которые остаются с ней в согласии, и обслуживает её как [мок](/docs/mocks), пока самого API ещё нет.

Откройте её через **Спецификации** в переключателе разделов боковой панели или нажмите <kbd>⌘</kbd><kbd>3</kbd>.

<Shot id="specs-page" alt="Страница «Спецификации» с открытым в визуальном редакторе файлом alpenglow.yaml: боковая панель показывает спецификацию со структурой эндпоинтов и схем, на странице карточки «Обзор», «Серверы» и «Эндпоинты»" />

## Спецификации в рабочем пространстве [#specs-in-the-workspace]

Спецификации — это файлы в папке `specs` рабочего пространства, поэтому они попадают в Git вместе со всем остальным. В
примере Alpenglow их три: `alpenglow.yaml` (документ OpenAPI магазина), `shop.graphql` и `inventory.proto`. Страница
«Спецификации» перечисляет документы OpenAPI в разделе **Спецификации**, а файлы `.proto` — в разделе **Proto-файлы**.
Схемы GraphQL в этой папке используются [запросами GraphQL](/docs/requests/graphql) и здесь не перечисляются.

Кнопка **+** в заголовке **Спецификации** боковой панели добавляет спецификацию:

| Пункт | Что делает |
| --- | --- |
| **Новая спецификация** | Создаёт документ OpenAPI 3.1 с названием `New API` и открывает его в визуальном редакторе. |
| **Новая спецификация из ответов…** | Пишет спецификацию по отправленным вами запросам и полученным ответам. См. [Спецификация из ответов](/docs/specs/specs-from-traffic). |
| **Добавить файл спецификации…** | Копирует документ OpenAPI или Swagger (YAML или JSON) с вашего Mac в папку `specs`. |
| **Новый proto-файл** | Создаёт файл `.proto` на основе небольшого примера сервиса. См. [файлы .proto](/docs/specs/proto-files). |
| **Добавить proto-файл…** | Копирует файл `.proto` в папку `specs`. |

[Импорт](/docs/get-started/importing) документа OpenAPI командой **Файл › Импортировать…** — другое дело: он создаёт из
документа запросы, а не спецификацию, которую можно править.

Щёлкните спецификацию правой кнопкой, чтобы выбрать **Создать запросы**, **Показать в Finder**,
**Экспорт** (**В YAML…** или **В JSON…**) и **Удалить…**. Удаление сначала спрашивает разрешения и перемещает файл в
Корзину; файлы, на которые он ссылается, остаются, как и его моки.

## Структура [#the-outline]

Щёлкните спецификацию, чтобы открыть её. Под списком боковая панель показывает её структуру:

- **Обзор**: название, версия и описание.
- **ЭНДПОИНТЫ**: каждая операция с методом и путём. Устаревшие зачёркнуты. Наведите указатель на операцию, чтобы
  увидеть её сводку.
- **СХЕМЫ**: переиспользуемые схемы.
- **Файлы**, если спецификация ссылается на другие файлы (см. [Спецификации из нескольких файлов](#specs-split-across-files)).

Щёлкните элемент, чтобы открыть его: в визуальном редакторе открывается и прокручивается в поле зрения его карточка, в
коде редактор переходит на его строку.

## Визуально и код [#visual-and-code]

Переключатель **Редактор** в заголовке страницы выбирает, как вы видите открытую спецификацию:

- **Визуально**: карточки обзора, серверов, эндпоинтов и схем, которые правятся полями и меню.
- **Код**: документ в виде YAML или JSON, с номерами строк.

Оба режима правят один и тот же текст, и Echolot сохраняет его вскоре после каждого изменения. Оба описаны в разделе
[Правка спецификации](/docs/specs/editing).

## Проблемы [#problems]

Echolot проверяет спецификацию линтером по мере правки. Панель над редактором показывает **Проблем нет** либо число
ошибок и предупреждений. Красное число ошибок стоит и рядом с открытой спецификацией в боковой панели.

<Shot id="specs-problems" alt="Всплывающее окно «Проблемы» над спецификацией: ошибки и предупреждения, у каждого сообщение и номер строки" />

Щёлкните его, чтобы увидеть список: сначала ошибки, затем предупреждения и подсказки, у каждого своя строка. Выберите
проблему, чтобы перейти на эту строку. Если список пуст, там написано, что документ соответствует спецификации
OpenAPI и все ссылки разрешаются.

Что, среди прочего, проверяет линтер:

- Версию `openapi`, которую понимает Echolot, `info` с названием и версией и пути, начинающиеся с `/`.
- Параметры пути, которые есть в пути и помечены `required: true`, и параметры, которые не определены дважды.
- Описание у каждого ответа и идентификаторы операций, которые встречаются один раз.
- Теги, объявленные наверху, определённые схемы безопасности, массивы с `items` и перечисления со значениями.
- Ссылки, которые на что-то указывают, в этом файле или в другом файле из `specs`.
- Отсутствие `servers`: тогда созданные из спецификации запросы начинаются с `{{baseUrl}}`, которую вы задаёте сами.

Утилита командной строки запускает тот же линтер в CI: см. [echolot spec](/docs/cli/spec).

## Спецификации из нескольких файлов [#specs-split-across-files]

Спецификация может подключать части других файлов через `$ref`, например `$ref: schemas/pet.yaml#/Pet`. Файлы должны
находиться внутри папки `specs` рабочего пространства. Боковая панель перечисляет их в разделе **Файлы**: щёлкните
файл, чтобы открыть его в режиме **Код**. В редакторе кода наведите указатель на `$ref`, чтобы увидеть, на что он
указывает, и щёлкните по нему с нажатой клавишей <kbd>⌘</kbd>, чтобы перейти туда, в этом файле или в другом.

Echolot читает части вместе везде, где использует спецификацию: в линтере, при создании запросов, в моках. При экспорте
спецификации файлы, на которые она ссылается, записываются в один сохраняемый вами файл.

## Экспорт [#exporting]

**Экспорт** на панели над редактором (**Экспортировать как YAML…** или **Экспортировать как JSON…**) сохраняет
спецификацию одним файлом вне рабочего пространства, записывая в него файлы, на которые она ссылается. Несохранённые
правки сначала сохраняются, так что экспорт — это то, что показывает редактор.

## Запросы, которые следуют спецификации [#requests-that-follow-the-spec]

**Создать запросы** на панели над редактором создаёт папку с названием спецификации и запросом для каждого эндпоинта и
открывает первый. Папка следует спецификации: когда спецификация меняется, можно применить изменения к её запросам, не
потеряв того, что вы в них правили.

Когда папка следует спецификации, кнопка превращается в **Запросы** — меню с пунктом **Проверить изменения для
«папка»…** для каждой папки, которая ей следует, и пунктом **Создать ещё одну папку**. Проверка открывает
**Синхронизацию OpenAPI**, где перечислено, что **Новое в спецификации**, **Изменено в спецификации** и **Удалено из
спецификации**. Отметьте нужные изменения и нажмите **Применить 1 изменение** (или **Применить 3 изменения** и так
далее). Ваши правки всегда остаются; если вы и спецификация изменили одно и то же, сохраняется ваш вариант. Когда
операция исчезла, её запрос перемещается в Корзину, если только вы его не правили: тогда он остаётся и перестаёт
следовать спецификации. **Отвязать** прекращает следование папки спецификации и оставляет её запросы как есть.

Папка может следовать и спецификации вне рабочего пространства — файлу или URL: щёлкните папку в боковой панели
«Запросы» правой кнопкой и выберите **Связать со спецификацией OpenAPI…**. Утилита командной строки проверяет и
применяет изменения командами `echolot spec check` и `echolot spec apply`.