Перейти к основному содержимому

Доступные операции

Не все операции спецификации должны быть публичными. Административные методы, внутренние инструменты и черновые операции часто нужно сохранить в документе, но скрыть из опубликованной документации и MCP. Настройка доступности позволяет сделать это без изменения исходного документа.

Как это работает​

Настройки сохраняются отдельно от спецификации. Каждая запись ссылается на операцию и указывает, включена ли она:

  • если есть operationId, предпочтение отдаётся ему;
  • также сохраняются method и path — для проверки и работы со спецификациями без идентификаторов операций.

Исходный документ не меняется. Документация и MCP создаются на основе спецификации с учётом включённых операций. Выключенная операция исчезает из опубликованных интерфейсов, но остаётся в файле.

Интерфейс выбора операций​

Интерфейс рассчитан в том числе на большие спецификации:

  • Поиск — фильтрация по методу, пути, краткому описанию или тегу;
  • Группировка по тегу — по основному тегу; операции без тегов собираются отдельно;
  • Индивидуальное переключение — включение или выключение одной операции;
  • Действия с группой — включение или выключение всех операций с определённым тегом;
  • Выбор всех результатов фильтра — общий флажок применяется только к операциям, соответствующим текущему поиску.

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

Практический подход​

Можно начать со всех включённых операций, а затем выключить те, которые не должны быть публичными:

  • внутренние и административные методы, например управление пользователями или внутренние проверки состояния;
  • операции, которые ещё проектируются;
  • методы только для локальной отладки.

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

Связь с публикацией​

Эта настройка определяет, какие операции показывать. Другие ограничения определяют, доступен ли сам документ:

  • документ должен иметь статус ACTIVE;
  • документация и MCP включаются независимо;
  • для документации может требоваться пароль, а для MCP — ключ доступа.

Полный список ограничений описан в разделе Управление доступом.

Ограничения тарифов​

Тариф ограничивает число доступных операций:

  • Free — до 10;
  • Pro — до 1 000;
  • Team — до 10 000.

См. также: Управление доступом, Документы и версии.