Использование SmartDocs для документирования API

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

SmartDocs позволяет документировать ваши API на портале разработчиков Drupal 7 таким образом, чтобы документация по API была полностью интерактивной. Интерактивная документация означает, что пользователи портала могут:

  • Прочтите о своих API
  • Отправьте живой запрос к вашему API
  • Просмотр оперативного ответа, полученного от API

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

API управления Edge — это RESTful API, который позволяет вам получать доступ к службам API с помощью любого HTTP-клиента. Apigee использует SmartDocs для создания интерактивной документации для API управления Edge. См. документацию по API здесь .

Пример портала SmartDocs

Чтобы использовать SmartDocs, у вас должен быть портал Apigee Developer Services. Дополнительные сведения см. в разделе Создание портала разработчика .

На домашней странице портала разработчика нажмите «API» в верхней панели навигации, чтобы просмотреть страницу документации API.

На портале задокументировано два API: Hello World и Пример зоомагазина.

API Hello World был создан на основе спецификации OpenAPI макета целевой цели, mocktarget.yaml . Для получения дополнительной информации см. https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi .

Пример API зоомагазина был создан на основе классической демонстрации зоомагазина.

Изучите API Hello World:

  1. Нажмите Hello World API . Отображается страница сводки API Hello World:
  2. Нажмите «Просмотреть подтверждение API» . Отобразятся SmartDocs для этого ресурса:
  3. Нажмите Отправить этот запрос .
  4. Просмотрите полученный ответ: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. Щелкните вкладку «Запрос» , чтобы просмотреть запрос, или вкладку «cURL» , чтобы просмотреть соответствующий вызов cURL.

Как документировать свои API с помощью SmartDocs

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

Общие шаги, которые необходимо выполнить для использования SmartDocs:

  1. Настройте модуль Drupal SmartDocs на портале.
  2. Создайте модель SmartDocs.
  3. Добавьте API в модель из файла WADL, спецификации OpenAPI (ранее Swagger) или вручную.
  4. Отобразите модель как набор узлов Drupal. Каждый узел Drupal содержит информацию об одном API. Например, если ресурс в вашем API поддерживает как запрос POST, так и запрос PUT, SmartDocs создает отдельный узел Drupal для POST и PUT.
  5. Опубликуйте узлы Drupal. После публикации пользователи вашего портала смогут просматривать ваш API и взаимодействовать с ним.
  6. Редактируйте узлы Drupal до или после их публикации. Вы можете редактировать узлы Drupal, используя редактор Drupal или отредактировав исходный файл WADL или спецификацию OpenAPI. Завершив редактирование файла WADL или спецификации OpenAPI, импортируйте его обратно в модель как новую версию, а затем визуализируйте и опубликуйте изменения.
  7. Включите ТЛС . Поскольку SmartDocs может отправлять учетные данные для аутентификации на ваш сервер как часть запроса к вашим API, вам следует включить TLS на своем портале, чтобы гарантировать безопасность этих учетных данных. В производственной и тестовой средах портала Apigee предоставляет сертификат TLS, необходимый для выполнения запросов https://. Однако прежде чем начать работу с порталом, вы должны получить собственный сертификат TLS и включить TLS. Дополнительные сведения см. в разделе Использование TLS на портале .

О моделях и шаблонах SmartDoc

Когда вы создаете модель на своем портале, она фактически хранится в вашей организации Edge, а не в Drupal. Модель — это большой блок JSON с внутренним именем (например, «my-smartdocs-api»), определяющий структуру API. С другой стороны, ваш портал отображает модель в формате HTML и предоставляет интерфейс редактирования модели. Любые обновления API на портале автоматически возвращаются в исходную модель.

Хранится в организации

Хранится в Друпале

модели

шаблоны

Узлы Drupal с возможностью редактирования

Предположим, что в вашей организации есть несколько порталов (например, портал разработки, этап и производство). В Пантеоне вы перемещаете портал из одной среды в другую. Каждый экземпляр портала выглядит так, будто содержит собственную модель, но на самом деле все они ссылаются на исходную модель. Если вы редактируете API в разработке, модель обновляется, и изменения появляются в рабочей среде. Аналогично, если вы удалите модель в разработке, источник будет удален, и он больше не будет доступен в производстве.

Шаблоны управляют внешним видом ваших SmartDocs, и эти шаблоны (управляемые панелями управления и файлами CSS) хранятся с каждым экземпляром портала. Таким образом, каждый портал теоретически может использовать уникальный шаблон для каждой модели. Однако одним из преимуществ платформы рендеринга является то, что к каждой модели автоматически применяется шаблон по умолчанию (либо шаблон по умолчанию Apigee, либо предоставленный вами шаблон).

На следующей диаграмме показаны взаимосвязи между моделями и порталами. Зеленые стрелки показывают автоматическую синхронизацию.

Следующая команда cURL выводит список всех моделей в вашей организации:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

Настройка модуля SmartDocs

Apigee реализовала SmartDocs как собственный модуль Drupal. Используйте следующую процедуру для настройки модуля SmartDocs.

Чтобы настроить модуль SmartDocs:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Модули» в меню администрирования Drupal. Появится список всех установленных модулей Drupal.
  3. Включите модуль SmartDocs .
  4. Сохраните конфигурацию.
  5. Выберите «Модули» в меню администратора Drupal.
  6. Выберите SmartDocs -> Разрешения и убедитесь, что «Выполнение задач администрирования для модуля SmartDocs» для роли «Администратор» включено.
  7. Выберите Конфигурация > Портал разработки в меню администрирования Drupal.
  8. Установите время ожидания соединения и время ожидания запроса на 16 секунд.
  9. Сохраните конфигурацию.
  10. Настройте параметры URL-адреса:
    1. В меню Drupal выберите Конфигурация > Поиск и метаданные > Псевдонимы URL-адресов > Настройки .
    2. Установите максимальную длину псевдонима и максимальную длину компонента на 255 .
    3. Разверните пунктуацию .
    4. Для параметров Левая фигурная скобка ({) и Правая фигурная скобка (}) выберите Нет действия (не заменять) .
    5. Нажмите Сохранить конфигурацию .
  11. Если ваш портал разработчика будет доступен пользователям во внутренней сети без доступа к Интернету или если часть ваших API находится в частной сети, настройте URL-адрес прокси-сервера SmartDocs API следующим образом:
    1. Выберите Конфигурация > SmartDocs в меню администрирования Drupal.
    2. Разверните Дополнительные настройки .
    3. Обновите поле URL-адреса прокси-сервера SmartDocs следующим образом: < host >/smartdocs/v1/sendrequest .
      Встроенная справка должна обеспечивать необходимую ценность для вашей среды. Например:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      По умолчанию это поле имеет значение https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. Нажмите Сохранить конфигурацию .

Создание модели

Модель содержит всю информацию о представлении вашего API. Вы можете определить на портале несколько моделей для поддержки разных API или сгруппировать все свои API в одну модель.

Каждая модель определяет уникальное внутреннее имя, которое также определяет базовый URL-адрес сгенерированных узлов Drupal. URL-адрес каждого узла Drupal имеет вид:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

где:

  • drupalBasePath : базовый URL-адрес вашего портала.
  • InternalName : внутреннее имя модели.
  • httpMethod : HTTP-метод API, например: get, put, post или delete.
  • resourcesPath : путь к ресурсу.

Например, если вы укажете внутреннее имя как «mymodel», то URL-адрес сгенерированного узла Drupal для запроса GET к ресурсу с именем «/books» будет следующим:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

Чтобы создать модель

Когда вы создаете модель, она сохраняется в вашей организации Edge в качестве источника структуры API. Дополнительную информацию см. в разделе О моделях и шаблонах SmartDoc .

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Выберите «Новая модель» вверху страницы.
  4. Введите следующие поля:
    • Имя : название модели, которое будет отображаться на сайте.
    • Внутреннее имя : при вводе имени отображается внутреннее имя. Внутреннее имя модели, которое должно быть уникальным среди всех моделей. Внутреннее имя должно содержать только строчные буквы, цифры и дефисы без пробелов. Выберите «Изменить» , чтобы изменить это имя.
    • Описание : Описание модели.
  5. Выберите Создать модель .

После создания модели вы будете перенаправлены на страницу модели. Отсюда вы можете использовать раскрывающийся список «Операции» bx, чтобы:

  • Импортируйте файл WADL, описывающий ваш API, или укажите URL-адрес спецификации OpenAPI, описывающей ваш API.
  • Добавить ревизию в модель
  • Измените настройки модели, включая таблицы стилей, используемые моделью.
  • Экспортируйте модель в файл.
  • Удалить модель.

Добавление API в модель

Вы можете добавить API в модель следующим образом:

  • Импорт файла WADL, содержащего определение API
  • Импорт спецификации OpenAPI (OpenAPI 2.0 или 1.2)
  • Создание ресурсов и методов вручную.

Вы также можете импортировать файл SmartDocs JSON в модель. Этот файл обычно создается путем экспорта существующей модели, редактирования файла и последующего импорта обновлений. Дополнительную информацию см. в разделе « Экспорт и импорт модели » ниже.

Видео: посмотрите короткое видео, чтобы узнать, как добавить API в модель SmartDocs путем импорта спецификации OpenAPI.

Импортировать WADL

После успешного создания модели импортируйте файл WADL, описывающий ваш API. Каждый раз, когда вы импортируете файл WADL, вы автоматически создаете новую версию модели.

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Выберите модель, которую хотите обновить.
  4. В разделе «Операции» выберите «Импорт» .
  5. Выберите WADL в раскрывающемся списке «Выбрать формат» на странице импорта SmartDocs.
  6. Выберите «Файл» или «URL-адрес» в раскрывающемся списке «Тип загрузки» .
    1. Если вы выберете Файл , перейдите к файлу WADL.
    2. Если вы выберете URL , укажите URL-адрес файла WADL.
  7. Нажмите «Импортировать» , чтобы импортировать его в модель. Теперь вы можете визуализировать модель.
  8. Вы будете перенаправлены на информационную страницу модели, где теперь сможете визуализировать модель.

Импортируйте спецификацию OpenAPI

После успешного создания модели вы можете импортировать спецификацию OpenAPI (ранее Swagger). Edge поддерживает OpenAPI версий 1.2 и 2.0.

OpenAPI использует файлы, содержащие объекты JSON, для описания API. Каждый раз, когда вы импортируете спецификацию OpenAPI, вы автоматически создаете новую версию модели.

Чтобы импортировать спецификацию OpenAPI:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Выберите модель, которую хотите обновить.
  4. В разделе «Операции» выберите «Импорт» .
  5. Выберите Swagger JSON или Swagger YAML в раскрывающемся списке «Выбрать формат» на странице импорта SmartDocs.
  6. Выберите «Файл» или «URL-адрес» в раскрывающемся списке «Тип загрузки» (необходимо выбрать URL-адрес для OpenAPI 1.2).
    1. Если вы выберете File , перейдите к спецификации OpenAPI.
    2. Если вы выберете URL-адрес , укажите URL-адрес спецификации OpenAPI.
  7. Нажмите «Импортировать» , чтобы импортировать его в модель.
  8. Вы будете перенаправлены на информационную страницу модели, где теперь сможете визуализировать модель.

Создание ресурсов и методов вручную.

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

Чтобы вручную добавить API:

  1. Создайте новую редакцию модели.

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

    https://myCompany.com/v1

    Когда вы добавляете ресурсы в модель, они расширяют базовый путь.
  2. Определите один или несколько ресурсов для модели. Путь к ресурсу объединяется с базовым путем версии модели, чтобы указать полный URL-адрес ресурса. Например, если ваш ресурс определяет путь «/login», полный URL-адрес ресурса будет следующим:

    https://myCompany.com/v1/login
  3. Определите один или несколько методов для каждого ресурса. Метод указывает HTTP-команду, которую можно вызвать для ресурса. Например, для ресурса «/login» вы поддерживаете POST для входа в систему и DELETE для выхода из системы. Этот ресурс не поддерживает другие команды HTTP, такие как PUT или GET. Поэтому определите для ресурса два метода: один для POST и один для DELETE.

    Метод использует URL-адрес ресурса из родительского ресурса. Таким образом, все методы с одним и тем же URL-адресом определяются в одном ресурсе в SmartDocs.

Как правило:

  • Создайте другую модель SmartDocs для каждого уникального базового пути в вашем API.
  • Определите отдельный ресурс SmartDocs для каждого уникального ресурса в вашем API.
  • Определите отдельный метод SmartDocs для каждого HTTP-команд, поддерживаемого ресурсом.

Создание новой ревизии модели

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

Чтобы создать новую редакцию модели:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите обновить, выберите «Добавить ревизию» в разделе «Операции» .
  4. На странице «Добавить версию API» введите следующую информацию:
    • Отображаемое имя : имя редакции, отображаемое на портале.
    • Идентификатор версии : короткий идентификатор версии.
    • Описание : описание редакции.
    • Базовый URL-адрес : базовый URL-адрес всех API в версии модели. Модель может использовать разные базовые URL-адреса для каждой ревизии. Например, вы включаете индикатор версии в базовый URL-адрес. Для первой версии модели базовый URL-адрес:
      https://myCompany.com/v1
      Для следующей версии базовый URL-адрес может быть таким:
      https://myCompany.com/v2
  5. Выберите Добавить редакцию . Вы будете перенаправлены на страницу редакции модели. Теперь вы можете определять ресурсы в модели.

Определение ресурса

Ресурс указывает полный URL-адрес API. При определении ресурса вы указываете путь к ресурсу, который объединяется с базовым URL-адресом в версии модели для создания полного URL-адреса ресурса.

Чтобы определить ресурс:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите обновить, в разделе «Операции» выберите «Ревизии API» , чтобы просмотреть все версии модели.
  4. Выберите редакцию для редактирования.
  5. На странице редакции выберите «Добавить ресурс» в раскрывающемся меню.
  6. На странице «Добавить ресурс» введите следующую информацию:
    • Отображаемое имя : имя ресурса.
    • Путь : путь к ресурсу, начинающийся с «/». Значение Path объединяется с базовым URL-адресом версии модели для создания полного URL-адреса ресурса.
    • Описание : описание ресурса.
    • Параметры : при необходимости введите объект JSON, определяющий каждый параметр ресурса. Эти параметры описаны ниже.
  7. Выберите Добавить ресурс . Вы будете перенаправлены на страницу модели. Теперь вы можете определять методы ресурса.

При желании вы можете добавить к ресурсу параметры, такие как параметры шаблона, запроса и заголовка. Все параметры ресурса наследуются любыми методами, определенными в этом ресурсе. Таким образом, если вы определяете параметр запроса для ресурса, все методы, добавленные к этому ресурсу, должны поддерживать этот параметр запроса.

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

На следующем изображении показана существующая страница SmartDocs для API приложения Apigee Approve или Revoke Developer с выделенным каждым типом параметра:

Каждый тип параметра определяется объектом JSON:

Тип

JSON-объект

Примечания

Шаблон

{
"dataType": "строка",
"defaultValue": "",
"description": "Название организации.",
"name": "имя_организации",
«обязательно»: правда,
"тип": "ШАБЛОН"
}

Параметры шаблона всегда необходимы, поэтому установите для параметра require значение true и опустите значение defaultValue .

Значение описания появляется во всплывающем окне, когда пользователь наводит курсор на URL-адрес на странице SmartDocs.

Запрос

{
"dataType": "строка",
"defaultValue": "",
"description": "Местоположение.",
"имя": "ш",
«обязательно»: правда,
"тип": "ЗАПРОС"
}

Обязательные параметры запроса по-прежнему могут указывать значение defaultValue , но часто этого не делают.

Для необязательных параметров запроса установите для параметра обязательно значение false и укажите значение defaultValue .

Заголовок

{
"dataType": "строка",
"defaultValue": "приложение/json",
"description": "Укажите как <code>application/json</code>.",
"name": "Тип контента",
«обязательно»: правда,
"тип": "ЗАГОЛОВОК"
}

Обратите внимание, как вы можете использовать HTML-теги в описании.

Параметр шаблона определяет переменную в пути к ресурсу. Например, вы определяете для ресурса два параметра шаблона. Обратите внимание, что каждое определение параметра в массиве параметров разделено запятой:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

Затем вы можете использовать параметры шаблона в определении пути ресурса, заключенном в «{}». Например, укажите путь:

/login/{org_name}/{developer_email}

На странице API SmartDocs пользователь должен отредактировать URL-адрес, указав часть URL-адреса org_name и Developer_email, прежде чем он сможет отправить запрос.

Определение метода

Определите один или несколько методов для каждого ресурса. В определении метода указывается команда HTTP, которую можно вызвать для ресурса. Ресурс может иметь один или несколько методов.

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

На следующем изображении показана существующая страница SmartDocs для Apigee Create Developer API, где каждая область страницы выделена соответствующим значением, которое вы установили при определении метода:

На следующем изображении показана та же страница, но с выбранным описанием тела запроса:

Чтобы определить метод:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите обновить, в разделе «Операции» выберите «Ревизии API» , чтобы просмотреть все версии модели.
  4. Выберите редакцию для редактирования.
  5. На странице редакции выберите «Добавить метод» в раскрывающемся меню для одного из ресурсов.
  6. На странице «Редактировать метод» введите следующую информацию:
    • Отображаемое имя : имя API, которое также становится заголовком страницы Drupal для API.
    • Описание : Опишите API.
    • Метод Verb : тип HTTP-глагола.
    • Схемы безопасности : укажите режим аутентификации, если таковой имеется, для метода. Дополнительную информацию см. в разделе Настройка типа аутентификации SmartDocs .
    • Тип контента : тип контента запроса и ответа. См. раздел ниже о настройке различных методов аутентификации.
    • Параметры : (необязательно) любые параметры запроса или заголовка для метода. Дополнительную информацию см. в описании выше для добавления параметра к ресурсу.
    • Документация по телу запроса : (Необязательно) Опишите тело запроса. Методы POST и PUT принимают тело запроса. Вы можете использовать эту область для описания. Если вы опустите это значение, ссылка «Описание» в разделе «Тело запроса» будет исключена из созданной страницы SmartDocs.
    • Пример тела запроса : (необязательно) Покажите пример тела запроса, обычно в виде объекта JSON или XML. Для команд POST и PUT пример тела запроса передается как часть каждого запроса. Пользователи страницы SmartDocs редактируют этот пример перед отправкой запроса в API. Если вы опустите это значение, ссылка «Значение» в разделе «Тело запроса» будет исключена из сгенерированной страницы SmartDocs.
    • Теги : массив тегов, связанных с API. SmartDocs использует теги для группировки похожих API. Например, вы можете применить тег «Статистика» ко всем API статистики. Вы можете группировать API из разных ресурсов под одним тегом. если все они используют один и тот же тег.
  7. Выберите Добавить метод . Вы будете перенаправлены на страницу модели. Теперь вы можете визуализировать и опубликовать свой метод.

Рендеринг модели

После добавления API в модель вы можете визуализировать модель. Рендеринг преобразует описание модели API в узлы Drupal. После завершения рендеринга у вас будет один узел Drupal для каждого API, где каждый узел Drupal соответствует HTML-странице.

Вы можете выполнить рендеринг всей модели сразу или выбрать отдельные API для рендеринга.

Чтобы визуализировать модель:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите визуализировать, выберите «Версии API» в разделе «Операции».
  4. Выберите ревизию, которую хотите визуализировать. Вы можете визуализировать узлы только из одной ревизии модели.
  5. Выберите методы рендеринга.
  6. Выберите «Узлы рендеринга» в раскрывающемся списке « Параметры обновления» .
  7. Нажмите Обновить .
  8. Появится экран загрузки, на котором можно просмотреть ход рендеринга ваших узлов.
    После визуализации узлов идентификатор узла Drupal для каждого API отображается в столбце «Ассоциация узла» модели. Нажмите на ссылку в столбце «Ассоциация узлов» , чтобы увидеть визуализированный узел.

Вместо выбора узлов рендеринга вы можете выбрать узлы рендеринга и публикации для рендеринга и немедленной публикации API в качестве узла Drupal.

Публикация узлов

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

Чтобы опубликовать узел:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите опубликовать, выберите «Версии API» в разделе «Операции».
  4. Выберите редакцию, которую хотите опубликовать. Публиковать узлы можно только из одной ревизии модели.
  5. Выберите методы публикации.
  6. Выберите узлы в редакции для публикации.
  7. Выберите узлы публикации в раскрывающемся списке параметров обновления .
  8. Нажмите Обновить .
  9. Перейдите к узлу, выбрав идентификатор узла в столбце «Ассоциация узла» .

По умолчанию URL-адрес Drupal опубликованного узла API имеет форму: http://< drupalBasePath >/< InternalName >/apis/< httpMethod >/< resourcesPath > . Используйте следующую процедуру для управления формой URL-адреса:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. В меню администрирования Drupal выберите Конфигурация > Поиск и метаданные > Псевдонимы URL-адресов > Шаблоны .
  3. В разделе «Шаблон для всех путей к методам SmartDocs» укажите, как вы хотите создать путь.
  4. Выберите Сохранить конфигурацию .

Из-за кэширования на портале вы можете не увидеть страницы своих моделей сразу после их публикации. При необходимости вы можете вручную очистить HTML-кеш SmartDocs, выполнив следующую процедуру:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите Конфигурация > SmartDocs в меню администрирования Drupal.
  3. Нажмите «Перестроить кэши моделей SmartDocs» .

Отмена публикации узла

Вы можете отменить публикацию опубликованного узла в любое время. Отмена публикации узла делает его невидимым для пользователей портала.

Чтобы отменить публикацию узла:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, публикацию которой вы хотите отменить, выберите «Версии API» в разделе «Операции».
  4. Выберите версию модели узла, публикацию которого вы хотите отменить.
  5. Выберите узлы в ревизии, публикацию которой требуется отменить.
  6. Выберите «Отменить публикацию узлов» в раскрывающемся списке « Параметры обновления» .
  7. Нажмите Обновить .

Просмотр версии модели

Вы создаете новую версию модели, импортируя новый файл WADL или спецификацию OpenAPI в существующую модель или создавая новую версию вручную. После создания новой ревизии вы можете отобразить и опубликовать ревизию, которая заменит опубликованные в данный момент узлы Drupal.

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

Чтобы увидеть версию модели:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите обновить, выберите «Версии API» в разделе «Операции».
  4. Выберите версию модели, которую хотите просмотреть.
  5. Отрисуйте и опубликуйте узлы, как описано выше.

Редактирование узла

После визуализации узла его можно редактировать с помощью редактора Drupal. Например, вы можете отредактировать команду HTTP и описание API или добавить в API новый запрос или параметр заголовка. Вы можете редактировать узлы, созданные из файла WADL или спецификации OpenAPI, или узлы, созданные вручную.

Вы также можете редактировать исходный файл WADL или спецификацию OpenAPI. Завершив редактирование, импортируйте файл WADL или спецификацию OpenAPI обратно в модель в качестве новой версии, а затем визуализируйте и опубликуйте изменения, как описано выше.

Чтобы отредактировать узел с помощью редактора Drupal:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Перейдите к узлу Drupal, соответствующему документации API, которую вы хотите редактировать.
  3. Выберите «Редактировать» , чтобы использовать редактор Drupal.
  4. После завершения редактирования выберите «Метод обновления» .

Альтернативно вы можете редактировать узел из модели SmartDocs:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
  3. Для модели, которую вы хотите обновить, выберите «Версии API» в разделе «Операции».
  4. Выберите версию модели, которую хотите опубликовать.
  5. Выберите «Изменить метод» в раскрывающемся списке «Операции» для метода, который вы хотите изменить.

Чтобы удалить узел:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
  3. Для модели, которую вы хотите обновить, выберите «Версии API» в разделе «Операции».
  4. Выберите версию модели, которую хотите опубликовать.
  5. Выберите «Удалить метод» в раскрывающемся списке «Операции» для этого метода.
    Внимание! Удаление узла также удаляет API из модели. Если вы хотите только отменить публикацию API, чтобы он был скрыт от пользователей портала, но не хотите удалять его из модели, вам следует отменить публикацию узла, как описано выше.

Портал имеет встроенный отчет, который отображает информацию о любом узле, отображаемом моделью SmartDocs, который больше не ссылается на действительные методы модели. Чтобы получить доступ к отчету, выберите «Отчеты» в меню Drupal, а затем выберите отчет с именем «Состояние узла SmartDocs» .

Экспорт и импорт модели

SmartDocs позволяет экспортировать существующую модель в файл. Например, вы можете определить производственную и промежуточную среду. Затем вы вносите все изменения SmartDocs в промежуточную среду. Когда вы будете готовы выпустить свои API, вы экспортируете промежуточную модель и импортируете ее в производственную модель.

Импорт модели создает новую версию модели. SmartDocs пытается сопоставить существующие API в модели с импортированными API. Если SmartDocs обнаруживает совпадение, импорт обновляет узел Drupal, соответствующий существующему API. Если SmartDocs не обнаруживает совпадения, при импорте создается новый узел Drupal для API.

Например, у вас есть API POST, соответствующий узлу Drupal с идентификатором 91. Затем вы импортируете модель, и SmartDocs обнаруживает соответствие API POST в импортированной модели существующему API POST. Любые обновления POST API затем обновляют узел Drupal 91. Если SmartDocs не обнаруживает совпадения, он создает новый узел Drupal с новым идентификатором.

Drupal выполняет сопоставление, используя следующие характеристики API:

  • InternalName : внутреннее имя модели.
  • httpMethod : метод HTTP API, например: GET, PUT, POST или DELETE.
  • resourcesPath : путь к ресурсу.
  • параметры запроса : любые параметры запроса, используемые API.

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

Экспортированная модель представлена ​​одним объектом JSON с записями для ресурсов и методов. Это означает, что вы можете редактировать экспортированную модель, чтобы изменить ресурс или метод, а затем повторно импортировать модель. Если вы редактируете объект JSON, не изменяйте следующие поля:

  • номер ревизии
  • созданноевремя
  • модифицированноевремя
  • APIRevisionId
  • идентификатор ресурса

Чтобы экспортировать модель:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите экспортировать, выберите «Экспорт» в разделе «Операции» .
  4. Выберите тип файла экспорта SmartDocs JSON .
  5. Нажмите «Экспорт» .
  6. Вам будет предложено сохранить файл на диск или открыть его в редакторе.

Чтобы импортировать модель:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите импортировать, выберите «Импорт» в разделе «Операции» .
  4. Выберите SmartDocs JSON в раскрывающемся списке «Выбрать формат» .
  5. Выберите Файл или URL-адрес в Тип загрузки:
    1. Если вы выберете Файл , перейдите к файлу JSON.
    2. Если вы выберете URL-адрес , укажите URL-адрес JSON-файла SmartDocs.
  6. Нажмите «Импортировать» , чтобы импортировать его в модель.
  7. Вы будете перенаправлены на информационную страницу модели, где теперь сможете визуализировать модель. Обратите внимание, что при импорте создается новая редакция модели.
  8. Отрисуйте и опубликуйте узлы.

Редактирование шаблона SmartDocs

Шаблон SmartDocs определяет, как ваши узлы Drupal отображаются на экране. Каждая модель SmartDocs может использовать один и тот же шаблон по умолчанию, или вы можете вручную настроить шаблон, используемый для отдельной модели.

Шаблон SmartDocs включает в себя файл шаблона, закодированный как файл Handlebars .hbr, файлы CSS и файлы JavaScript. При использовании Handlebars большая часть содержимого управляется переменными с использованием встроенных выражений handlebars, таких как &123;&123;body}} . Список существующих выражений Handlebar представлен в комментарии вверху файла. Информацию об использовании Handlebars для настройки шаблонов см. на странице http://handlebarsjs.com .

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

Загрузка пользовательского файла шаблона SmartDocs

Вы можете загрузить собственный файл шаблона SmartDocs в виде файла Handlebars .hbr, чтобы использовать его в качестве шаблона по умолчанию при создании новых моделей или импорте новых API в существующую модель.

Если вы хотите использовать файл шаблона SmartDocs по умолчанию в качестве отправной точки при создании собственного файла шаблона SmartDocs, вы можете загрузить копию по адресу: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

Чтобы загрузить собственный файл шаблона SmartDocs:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите Конфигурация > SmartDocs в меню администрирования Drupal.
  3. Разверните область «Дополнительные настройки» на странице.
  4. В разделе «Загрузить индивидуальный шаблон метода» нажмите «Выбрать файл» и перейдите к файлу Handlebars .hbr.
  5. Нажмите «Загрузить» .
  6. Нажмите Сохранить конфигурацию .

Восстановление файла шаблона SmartDocs по умолчанию

Вы можете восстановить файл шаблона SmartDocs по умолчанию. После восстановления файл шаблона SmartDocs по умолчанию будет использоваться при создании новых моделей или импорте новых API в существующую модель.

Чтобы восстановить файл шаблона SmartDocs по умолчанию:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите Конфигурация > SmartDocs в меню администрирования Drupal.
  3. Разверните область «Дополнительные настройки» на странице.
  4. В разделе «Загрузить индивидуальный шаблон метода» нажмите «Удалить» рядом с файлом пользовательского шаблона SmartDocs.
  5. Нажмите Сохранить конфигурацию .

Изменение шаблона SmartDocs для отдельной модели

Вы можете изменить шаблон, используемый для отдельной модели.

Чтобы изменить шаблон для отдельной модели:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выберите «Содержимое» > «SmartDocs» в меню администрирования Drupal.
  3. Для модели, которую вы хотите изменить, выберите «Настройки» в разделе «Операции» .
  4. В области «Шаблон метода» отредактируйте шаблон по мере необходимости.
  5. Нажмите Сохранить шаблон .
  6. Перейдите к узлу Drupal. Вы должны увидеть изменения вашего шаблона на странице.

Настройка типа аутентификации SmartDocs

API, определенные в SmartDocs, могут быть либо открытыми, то есть для доступа к ним не требуются учетные данные аутентификации, либо безопасными. Безопасный API требует, чтобы вы передавали учетные данные при вызове API.

Для безопасного API SmartDocs поддерживает следующие типы аутентификации:

  • Базовая аутентификация . Передайте учетные данные базовой аутентификации в виде пары имени пользователя и пароля. Если вы не укажете использование OAuth в качестве типа учетных данных, API по умолчанию будет использовать базовую аутентификацию.
  • OAuth 2.0 — сторонний поставщик услуг проверяет подлинность учетных данных пользователя, гарантирует, что пользователь имеет авторизацию для доступа к API, а затем выдает токен доступа. Когда вы отправляете запрос SmartDocs к защищенному API, SmartDocs формирует запрос и отправляет его поставщику услуг. Затем поставщик услуг проверяет токен и гарантирует, что срок его действия не истек.
  • Пользовательский токен . Передайте значение токена в качестве заголовка или параметра запроса для каждого запроса.

Для каждого типа аутентификации вы создаете схему безопасности , определяющую характеристики аутентификации. Например, для аутентификации настраиваемого токена схема безопасности определяет способ передачи токена (заголовок, параметр запроса, параметр тела) и имя токена.

Схема безопасности связана с конкретной версией модели. Поэтому, если вы создаете новую версию модели, вам придется переопределить схемы безопасности для этой версии.

В файле WADL вы указываете, требует ли API аутентификацию, используя тег <apigee:authentication> Apigee, как показано ниже:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

Если API открыт, установите для обязательного атрибута значение false .

Обратите внимание, что вы не можете указать тип аутентификации в файле WADL. Вы делаете это, редактируя узел в Drupal. Дополнительную информацию о файлах WADL см. в Справочнике WADL .

На странице API в Drupal SmartDocs добавляет следующую кнопку, позволяющую пользователям указать свои основные учетные данные для аутентификации:

Если вы отредактируете узел, чтобы установить тип аутентификации OAuth, SmartDocs добавит на страницу следующую кнопку:

Для пользовательского токена SmartDocs добавляет:

Настройка базовой аутентификации

Если вы используете базовую аутентификацию с вашим API, вам нужно только указать тег <apigee:authentication> в файле WADL, который вы используете для создания модели.

Чтобы применить базовую аутентификацию к методам, созданным из источника, отличного от файла WADL:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
  3. Для желаемой модели выберите «Версии API» в разделе «Операции».
  4. Для версии модели, которую вы хотите изменить, выберите «Настройки безопасности» в разделе «Операции» .
  5. Выберите Добавить схему безопасности .
  6. Укажите имя схемы безопасности.
  7. В качестве типа выберите «Базовый» .
  8. Выберите «Отправить» .
  9. Для каждого метода в модели отредактируйте метод, чтобы установить его схему безопасности в соответствии с вашей базовой схемой.
    1. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
    2. Для желаемой модели выберите «Версии API» в разделе «Операции».
    3. Для редакции модели, которую вы хотите отредактировать, выберите «Сведения о редакции» в разделе «Операции» .
    4. Выберите метод редактирования для API, который вы хотите изменить.
    5. Выберите схему безопасности для API.
    6. Сохраните API.

Настройка аутентификации OAuth 2.0

Вы можете настроить модель для использования OAuth 2.0 в SmartDocs вместо базовой аутентификации по умолчанию. Вы настраиваете OAuth в двух местах:

  1. Создайте схему безопасности для каждой ревизии модели в разделе «Настройки безопасности» для этой ревизии.
  2. Укажите идентификатор клиента и секрет клиента для всех версий модели в разделе «Настройки модели».

Чтобы включить OAuth:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
  3. Для желаемой модели выберите «Версии API» в разделе «Операции».
  4. Для версии модели, которую вы хотите изменить, выберите «Настройки безопасности» в разделе «Операции» .
  5. Выберите Добавить схему безопасности .
  6. Укажите имя схемы безопасности.
  7. В качестве типа выберите OAuth 2.0 .
  8. Установите тип гранта .
  9. Введите значения в поля URL-адрес авторизации . URL-адрес авторизации используется для получения токена доступа.
  10. Установите глагол авторизации как GET или POST.
  11. Введите URL-адрес токена доступа . URL-адрес токена доступа — это URL-адрес, используемый для обмена токена запроса на токен доступа.
  12. Введите имя параметра токена доступа .
  13. Используйте In , чтобы указать способ передачи токена: Header , Query или Body .
  14. Установите области действия OAuth.
  15. Выберите «Отправить» .
  16. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
  17. Для модели выберите «Настройки» в раскрывающемся списке «Операции» .
  18. Введите значения в поля Client ID и Client Secret .
  19. Выберите Сохранить настройки аутентификации по шаблону .
  20. Для каждого метода в модели отредактируйте метод, чтобы установить его схему безопасности в соответствии с вашей схемой безопасности OAuth.
    1. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
    2. Для желаемой модели выберите «Версии API» в разделе «Операции».
    3. Для редакции модели, которую вы хотите отредактировать, выберите «Сведения о редакции» в разделе «Операции» .
    4. Выберите метод редактирования для API, который вы хотите изменить.
    5. Выберите схему безопасности для API.
    6. Сохраните API.

Настройка аутентификации по пользовательскому токену

Вы можете настроить модель для использования пользовательской аутентификации по токену.

Чтобы включить пользовательские токены:

  1. Войдите на свой портал как пользователь с правами администратора или создания контента.
  2. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
  3. Для желаемой модели выберите «Версии API» в разделе «Операции».
  4. Для версии модели, которую вы хотите изменить, выберите «Настройки безопасности» в разделе «Операции» .
  5. Выберите Добавить схему безопасности .
  6. Укажите имя схемы безопасности.
  7. Выберите Apikey в качестве типа .
  8. Задайте имя параметра, содержащее токен.
  9. Используйте In , чтобы указать способ передачи токена: Header , Query или Body .
  10. Выберите «Отправить» .
  11. Для каждого метода в модели отредактируйте метод, чтобы установить его схему безопасности в соответствии с вашей схемой токена.
    1. Выбирать Содержимое > SmartDocs в меню администрирования Drupal.
    2. Для желаемой модели выберите «Версии API» в разделе «Операции».
    3. Для редакции модели, которую вы хотите отредактировать, выберите «Сведения о редакции» в разделе «Операции» .
    4. Выберите метод редактирования для API, который вы хотите изменить.
    5. Выберите схему безопасности для API.
    6. Сохраните API.

Удаление модели

Когда вы удаляете модель ( Содержимое > SmartDocs , Удалить в поле «Операции» в Drupal), модель удаляется из вашей организации Edge. Это означает, что если другие порталы ссылаются на модель, она больше не доступна. Дополнительную информацию см. в разделе О моделях и шаблонах SmartDoc .