Как опубликовать API (оригинальная версия)

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Опубликуйте API на портале, чтобы разработчики приложений могли их использовать. Инструкции приведены в следующих разделах.

Обзор публикации API

Публикация API на портале состоит из двух этапов:

  1. Выберите продукт API, который хотите опубликовать на портале.
  2. Автоматически создавайте справочную документацию по API на основе снимка спецификации OpenAPI, чтобы разработчики приложений могли изучать ваши API. Подробнее о снимках спецификации OpenAPI…

Когда вы публикуете API на портале, на нем автоматически выполняются следующие действия:

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

    Примечание. Содержимое этой страницы нельзя изменить напрямую. Она не показывается в списке страниц на портале.

  • На страницу API добавлен раздел "Справочная документация по API"
    На странице API (входит в образец портала) приведен список всех API, опубликованных на вашем портале, со ссылками на справочную документацию по каждому из них.

    Примечание. Содержимое этой страницы нельзя изменить напрямую. Она не показывается в списке страниц на портале.

Что такое снимок спецификации OpenAPI?

Каждая спецификация OpenAPI служит источником достоверной информации на протяжении всего жизненного цикла API. Одна и та же спецификация используется на каждом этапе жизненного цикла API, от разработки до публикации и мониторинга. При изменении спецификации необходимо учитывать, как это повлияет на API на других этапах жизненного цикла, как описано в разделе Что произойдет, если я изменю спецификацию?

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

Как добавить поддержку CORS в прокси API

Прежде чем публиковать API, вам нужно добавить поддержку CORS в прокси API, чтобы разрешить клиентские междоменные запросы.

CORS (совместное использование ресурсов между разными источниками) – это стандартный механизм, который позволяет вызовам JavaScript XMLHttpRequest (XHR), выполняемым на веб-странице, взаимодействовать с ресурсами из доменов, отличных от источника. CORS – это распространенное решение для правила ограничения источника, которое применяется во всех браузерах. Например, если вы выполните вызов XHR к Twitter API из кода JavaScript, выполняемого в браузере, вызов завершится неудачно. Это происходит потому, что домен, с которого страница загружается в браузер, не совпадает с доменом, с которого загружается Twitter API. CORS позволяет серверам разрешать совместное использование ресурсов между разными источниками.

Информацию о том, как добавить поддержку CORS в прокси-серверы API перед публикацией API, можно найти в статье Как добавить поддержку CORS в прокси-сервер API.

Примечание. Большинство современных браузеров поддерживают CORS. Ознакомьтесь с полным списком поддерживаемых браузеров. Подробное описание CORS приведено в рекомендациях W3C по совместному использованию ресурсов между разными источниками.

Как перейти на страницу API

Чтобы перейти на страницу API, выполните следующие действия:

  1. Выберите Опубликовать > Порталы и выберите нужный портал.
  2. На главной странице портала нажмите API.

Также можно выбрать API в раскрывающемся меню портала на панели навигации вверху.

Появится список API.

Документация по API

Как показано на рисунке выше, на странице API можно:

Как добавить API на портал

Примечание. На портал можно добавить не более 100 API.

Чтобы добавить API на портал:

  1. Выберите Опубликовать > Порталы и выберите нужный портал.
  2. На главной странице портала нажмите API.
    Также можно выбрать API в раскрывающемся меню портала на панели навигации вверху.
  3. Нажмите + API.
    Откроется диалоговое окно "Добавить продукт API на портал".

  4. На вкладке API Product (Продукт API) в диалоговом окне выберите продукт API, который хотите добавить на портал.

  5. Нажмите Далее.

  6. Выберите источник для снимка.
    Если вы создали прокси-сервер API, включенный в продукт API, с помощью спецификации OpenAPI, выберите спецификацию в раскрывающемся списке.
    Как добавить снимок

    Вы также можете выбрать:

    • Нет спецификации и добавить ее позже после публикации API, как описано в разделе Как сделать снимок спецификации.
    • Выбрать другие характеристики, чтобы выбрать или загрузить новые.

  7. Установите флажок Опубликовано, чтобы опубликовать API на портале. Снимите флажок Опубликовано, если вы не готовы опубликовать API.
    Вы можете изменить этот параметр позже, как описано в разделе Публикация и отмена публикации API на портале.

  8. В разделе "Аудитория" выберите один из следующих вариантов, чтобы управлять аудиторией API, предоставив доступ к:

    • Анонимные пользователи, чтобы разрешить всем пользователям просматривать страницу.
    • Зарегистрированные пользователи – страницу смогут просматривать только зарегистрированные пользователи.

    Вы можете изменить этот параметр позже, как описано в разделе Управление аудиторией API на портале.

  9. Нажмите Готово.

Сделайте снимок спецификации

После публикации API вы в любой момент можете сделать новый снимок спецификации OpenAPI, чтобы обновить справочную документацию по API, опубликованную на вашем портале.

Чтобы сделать снимок спецификации OpenAPI:

  1. Выберите Опубликовать > Порталы и выберите нужный портал.
  2. На главной странице портала нажмите API.
    Также можно выбрать API в раскрывающемся меню портала на панели навигации вверху.
  3. Наведите курсор на API, для которого вы хотите сделать снимок, чтобы отобразить действия.

  4. Нажмите Значок сводки.

    Примечание. Если снимок соответствует выбранному источнику, появится сообщение.

  5. Выберите существующую спецификацию в раскрывающемся списке "Источник снимка" или нажмите Выбрать другую спецификацию, чтобы выбрать или загрузить новую спецификацию для создания документации по API. Чтобы удалить текущую спецификацию, выберите Нет спецификации.

  6. Нажмите Обновить снимок (или Удалить снимок, если вы выбрали "Нет спецификации").

Справочная документация по API создается на основе спецификации и добавляется на страницу "Справочник по API".

Как опубликовать API на портале или отменить его публикацию

Чтобы опубликовать API на портале или отменить его публикацию:

  1. Выберите Опубликовать > Порталы и выберите нужный портал.
  2. На главной странице портала нажмите API.
    Также можно выбрать API в раскрывающемся меню портала на панели навигации вверху.
  3. Наведите курсор на API, который вы хотите опубликовать или отменить публикацию.
  4. Нажмите Значок настроек.
  5. Установите флажок Включено, чтобы опубликовать API на портале. Снимите флажок Включено, чтобы отменить публикацию API.
  6. Нажмите Сохранить.

Как управлять аудиторией API на портале

Настройте аудиторию для своего API на портале, предоставив доступ к:

  • Все пользователи
  • Только зарегистрированные пользователи

Чтобы управлять аудиторией для API на портале:

  1. Выберите Опубликовать > Порталы и выберите нужный портал.
  2. На главной странице портала нажмите API.
    Также можно выбрать API в раскрывающемся меню портала на панели навигации вверху.
  3. Наведите курсор на API, для которого вы хотите управлять аудиторией, чтобы отобразить действия.
  4. Нажмите Значок настроек.
  5. В разделе "Аудитория" выберите один из следующих вариантов:
    • Анонимные пользователи, чтобы разрешить всем пользователям просматривать продукт API.
    • Зарегистрированные пользователи – чтобы разрешить просмотр продукта API только зарегистрированным пользователям.
  6. Нажмите Сохранить.

Как удалить API из портала

Чтобы удалить API из портала:

  1. Выберите Опубликовать > Порталы и выберите нужный портал.
  2. На главной странице портала нажмите API.
    Также можно выбрать API в раскрывающемся меню портала на панели навигации вверху.
  3. Наведите курсор на API в списке, чтобы открыть меню действий.
  4. Нажмите Удалить.

Как устранять неполадки с опубликованными API

Если при использовании функции "Попробовать" возвращается ошибка TypeError: Failed to fetch, ознакомьтесь с возможными причинами и решениями ниже.

  • В случае ошибок со смешанным контентом проблема может быть связана с известной ошибкой swagger-ui. Чтобы обойти эту проблему, укажите HTTPS перед HTTP в определении schemes в спецификации OpenAPI. Пример: 

     schemes:
   - https
   - http

  • Если возникают ошибки, связанные с ограничениями CORS (совместного использования ресурсов между разными источниками), убедитесь, что CORS поддерживается прокси API. CORS – это стандартный механизм, который позволяет выполнять клиентские междоменные запросы. Подробнее о том, как добавить поддержку технологии CORS для прокси-сервера API… Также убедитесь, что в браузере включена функция CORS.