Edit me
Шаг 1: объект openapi > Шаг 2: объект info > Шаг 3: объект servers > Шаг 4: объект paths > Шаг 5: объект components > Шаг 6: объект security > Шаг 7: объект tags > Шаг 8: объект externalDocs

Объект externalDocs позволяет добавлять ссылки на внешнюю документацию. Можно добавлять ссылки на внешние документы в объекте paths.

Пример объекта externalDocs

Вот пример объекта externalDocs:

externalDocs:
  description: API Documentation
  url: https://openweathermap.org/api

Обратите внимание, что эта документация должна относиться в целом к API. Чтобы связать определенный параметр с дополнительной документацией, можно добавить объект externalDocs к объекту операции, как отмечено в описании Объекта operations в Шаге 4: Объект paths.

Отображение в Swagger UI

Добавим приведенный выше код к корневому уровню документа OpenAPI в интерфейсе Swagger.

В Swagger UI после описания API появится ссылка вместе с информацией об API:

externaldoc
Ссылка на внешнюю документацию

Итоговый результат

Теперь, когда мы выполнили все шаги в руководстве OpenAPI, мы закончили создание нашего документа спецификации OpenAPI. Итоговый вариант спецификации здесь: https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml

Вот как выглядит собранная в Swagger UI спецификация:

final

Попробуйте выполнить запрос в вышеприведенной версии и посмотрите на результат. В результате найдите значение temp в объекте main. Затем сделайте перерыв, выйдя на улицу и оцените, соответствует ли температура снаружи реакции.

🔙

Go next ➡