Редактор Swagger онлайн: OpenAPI с документацией Swagger UI

Swagger Editor — привычный способ писать спецификации OpenAPI. В Помощнике SA та же схема работы: код слева, документация справа, — плюс хранение в проектах, история версий, ссылки между файлами спецификации и проверка ИИ.

Как начать

1. Откройте песочницу OpenAPI. Там уже есть пример — API библиотеки; вернуть его можно через Файл → Пример.
2. Вставьте свою спецификацию или откройте файл (Файл → Открыть файл…, .yaml/.yml/.json; можно перетащить файл в редактор).
3. Справа появится документация как в Swagger UI: методы по тегам, параметры, тела запросов и ответов, схемы.

Что умеет редактор

• OpenAPI 3.x и Swagger 2.0 — документ определяется по полю openapi или swagger. Если поля нет, редактор предупредит, что документ не похож на спецификацию.
• Ошибки синтаксиса YAML/JSON и повторяющиеся ключи подсвечиваются в строках; пока ошибка не исправлена, справа остаётся последняя корректная версия документации.
• Переход по $ref: Ctrl+клик по ссылке открывает определение, в том числе в другом файле проекта (см. «OpenAPI из нескольких файлов»).
• Скачивание в YAML и JSON: Файл → Скачать. Текущий формат сохраняется как есть, с комментариями; другой формат конвертируется.
• Try it out в документации отправляет настоящий запрос из браузера на сервер из servers. Сервер API должен разрешать запросы с другого домена (CORS), иначе браузер их заблокирует.

В аккаунте

• Спецификация сохраняется кнопкой Сохранить (Ctrl+S); каждое сохранение с изменениями — новая версия, их можно сравнить и откатить.
• Ссылкой для просмотра можно поделиться с теми, у кого нет аккаунта: Артефакт → Поделиться ссылкой….
• На тарифах «Макс» и выше доступны ИИ-подсказки при наборе и ИИ-ревью спецификации по лучшим практикам.

Полезные преобразования

• Swagger 2.0 → OpenAPI 3.0: отдельный гайд.
• Схемы данных — диаграммой классов: «OpenAPI в PlantUML».
• Схемы — в JSON Schema для валидаторов: «OpenAPI в JSON Schema».

Пример: минимальная спецификация

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.ru/v1
paths:
  /orders/{id}:
    get:
      summary: Заказ по идентификатору
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        "200":
          description: Заказ
          content:
            application/json:
              schema: {$ref: "#/components/schemas/Order"}
        "404":
          description: Не найден
components:
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id: {type: string, format: uuid}
        status: {type: string, enum: [NEW, PAID]}

Справа появится метод GET /orders/{id} с параметром, двумя ответами и схемой Order.

Вопросы и ответы

Чем это отличается от editor.swagger.io? Принцип тот же, но спецификации хранятся в аккаунте и проектах с историей версий, разбиваются на файлы со ссылками между ними, ими можно делиться ссылкой, а ИИ-агенты могут читать и править их через MCP.

Можно ли сгенерировать код клиента или сервера? Генерации кода в редакторе нет. Скачайте спецификацию (YAML или JSON) и используйте OpenAPI Generator или аналог в своём проекте.

Где описан синтаксис? В документации по OpenAPI — с примерами, которые открываются в редакторе.