Ваш первый API в apiwerk

Вход и организация

1. Нажмите «В кабинет». На самостоятельном сервере выберите регистрацию на странице входа (если она открыта администратором), подтвердите адрес почты и войдите. Если письмо не пришло, проверьте спам или обратитесь к администратору сервера. В демонстрации Sites используется вход через ChatGPT.
2. При первом входе создаётся личная организация. Её можно выбрать вверху кабинета; для другого проекта создайте отдельную организацию. API, участники и публикации принадлежат выбранной организации.

apiwerk размещает документацию, а не сервер вашего API. Адреса servers в OpenAPI должны указывать на работающий API, который вы обслуживаете отдельно.

Добавление API

1. В каталоге API нажмите «Импортировать API». Для готового OpenAPI загрузите .json, .yaml или .yml либо вставьте текст. Для Postman или Insomnia сначала выберите вкладку «Коллекция» — порядок преобразования описан ниже. Для знакомства можно выбрать демонстрационный контракт.
2. Поддерживаются OpenAPI 3.0 и 3.1; поддержка 3.2 экспериментальная. Один файл в UTF-8 до 5 МиБ. Укажите info.title, info.version и объект paths. Внешние ссылки $ref не загружаются: заранее объедините контракт в один файл с локальными ссылками.
3. Название и адрес можно заполнить самостоятельно или получить из info.title при проверке. Версия берётся из info.version. Русское название допустимо — адрес автоматически транслитерируется. Нажмите кнопку проверки и импорта.

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

Postman и Insomnia

Можно начать с HTTP-коллекции: Postman Collection 2.0 или 2.1 в JSON, Insomnia export v4 в JSON (старый формат) либо коллекция Insomnia v5 в YAML. Коллекция преобразуется в редактируемый черновик OpenAPI — это отправная точка документации, а не полный контракт и не средство запуска тестов.

1. Откройте «Импортировать API» и вкладку «Коллекция». Загрузите один файл .json, .yaml или .yml в UTF-8 либо вставьте его содержимое. Входной файл и полученный OpenAPI должны быть не больше 5 МиБ каждый.
2. Нажмите «Преобразовать коллекцию». Проверьте количество импортированных операций, пропуски и предупреждения. Преобразование выполняется в браузере; запросы из коллекции не отправляются, скрипты не запускаются, окружения не выполняются и локальные файлы не читаются.
3. Просмотрите и исправьте полученный OpenAPI в поле исходника. Проверьте адрес сервера, методы, пути, параметры, авторизацию, тела и ответы. Схемы, выведенные из примеров, приблизительны: самостоятельно уточните обязательные поля, типы и коды ответов. Значения параметров, заголовков, тел и примеров ответов не переносятся.
4. Затем выполните обычную проверку и импорт. На сервер отправляется только проверяемый OpenAPI, не исходная коллекция. Новый API остаётся приватным до отдельной публикации. Откройте редактор, устраните ошибки качества, проверьте приватный предпросмотр и только затем публикуйте портал по инструкции ниже.

Пропуски нельзя считать готовой документацией: GraphQL, WebSocket, gRPC, исполняемые шаблоны, тесты и файловые вложения не превращаются в полноценный HTTP-контракт. Неразрешённые переменные и неоднозначные операции требуют проверки. Удаление значений не гарантирует удаления всех секретов: имена, описания, адреса и пути тоже могут содержать закрытые данные — просмотрите их перед импортом и публикацией.

Вкладка «Коллекция» доступна при создании нового API. Для существующего API преобразуйте коллекцию локально, скопируйте полученный OpenAPI в его редактор и продолжайте стандартную работу с черновиком; повторный глобальный импорт создаст ещё один API.

Редактор и форматы

В редакторе доступны исходник JSON/YAML и визуальное редактирование документирующих полей: названий, описаний и тегов. Изменения структуры контракта выполняйте в исходнике. Сохраните черновик и выполните проверку, прежде чем создавать ревизию.

В описания можно вставить файл .md, .markdown или .txt в UTF-8 (до 20 000 символов) и скачать текст как .md. Описания поддерживают безопасный Markdown: заголовки, списки, ссылки, цитаты, блоки кода и таблицы GFM. Произвольный HTML, исполняемый MDX и скрипты не выполняются. Текст API, который вы написали, не переводится автоматически при переключении интерфейса.

В портале отображаются схемы, параметры, ответы и несколько типов содержимого: JSON, XML, текст, формы и multipart. Кодовые примеры доступны на cURL, JavaScript и Python. Это представление контракта, не гарантия поддержки каждого расширения OpenAPI.

Первая публикация

1. Откройте управление API, проверьте отчёт качества и устраните блокирующие ошибки. Сравнение ревизий помогает увидеть несовместимые изменения.
2. После импорта или сохранения новой ревизии предпросмотр создаётся автоматически, если контракт прошёл необходимые проверки. Откройте его и проверьте справочник, поиск, схемы и скачивание исходника. Предпросмотр доступен только участникам организации.
3. Нажмите «Опубликовать»: это активирует публичную документацию. Скопируйте ссылку из раздела «Порталы» и проверьте её в приватном окне браузера без входа.

Новый API по умолчанию использует прямую публикацию: владелец может самостоятельно выпустить документацию из OpenAPI после проверки качества. Если включено независимое согласование, потребуется одобрение другого участника. Публикация не делает публичными черновики, приватные предпросмотры и внутренние обсуждения. Не добавляйте реальные ключи, пароли и персональные данные в примеры контракта.

Markdown и командный релиз

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

1. В разделе «Контент» выберите API, создайте руководство и сохраните его Markdown. Редактор показывает исходник и безопасный предпросмотр.
2. Сначала сохраните нужную ревизию OpenAPI и настройте порядок страниц в «Контенте». В управлении API откройте «Кандидаты релиза», задайте название и язык портала. Кандидат закрепит текущую сохранённую main и весь текущий набор руководств с их порядком. Смена языка не переводит содержимое.
3. Соберите артефакт и запросите ревью. Другой владелец, администратор или издатель, не участвовавший в подготовке, проверяет и одобряет именно эту сборку. После одобрения создайте и проверьте приватный предпросмотр. В блоке рабочего релиза обновите проверку качества (Quality Gate); после успешной проверки активируйте точный артефакт.

После изменения состава релиза требуется новая сборка и новое одобрение. Публикация обычного OpenAPI-предпросмотра не включает отдельные руководства автоматически.

Доступ и команда

Владелец или администратор приглашает участника по почте в разделе «Команда» и передаёт ему сгенерированную ссылку. Автоматической рассылки приглашений пока нет. Участник должен войти с тем же подтверждённым адресом почты и принять приглашение. Если ссылка была открыта до входа, после авторизации откройте её повторно.

• Владелец и администратор: управление организацией и участниками в пределах своей роли.
• Автор: работа с API и черновиками. Издатель: ревью и публикация. Читатель: просмотр доступных материалов.

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

Обновления и восстановление

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

При сообщении о конфликте обновите данные и повторно проверьте изменения. Если результат отправки не подтверждён, используйте повтор той же попытки в интерфейсе: не создавайте новый релиз вслепую. Перед уходом из редактора сохраните черновик или скачайте локальную копию, если интерфейс предлагает восстановление.

Ограничения раннего доступа

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

• Импорт нескольких связанных файлов и самостоятельные форматы AsyncAPI, GraphQL и Protobuf. Postman и Insomnia доступны только через ограниченное преобразование HTTP-коллекции в OpenAPI, без выполнения запросов и тестов.
• Исполняемый MDX, полноценный структурный визуальный конструктор и автоматический перевод документации.
• Реальные запросы Try it, проксирование API, выдача ключей потребителям, биллинг и аналитика использования API.
• Самостоятельное подключение доменов к отдельным порталам. На VPS используется домен установки и пути /docs/….

Если действие недоступно, проверьте выбранную организацию, свою роль и завершение предыдущего шага. Для вопросов о регистрации, почте, лимитах и сохранности данных обращайтесь к администратору конкретной установки.