| Шаг 1: объект openapi | --> | Шаг 2: объект info | --> | Шаг 3: объект servers | --> | Шаг 4: объект paths | --> | Шаг 5: объект components | --> | Шаг 6: объект security | --> | Шаг 7: объект tags | --> | Шаг 8: объект externalDocs |
Объект externalDocs позволяет добавлять ссылки на внешнюю документацию. Можно добавлять ссылки на внешние документы в объекте paths.
Вот пример объекта externalDocs:
externalDocs:
description: API Documentation
url: https://openweathermap.org/apiОбратите внимание, что эта документация должна относиться в целом к API. Чтобы связать определенный параметр с дополнительной документацией, можно добавить объект externalDocs к объекту операции, как отмечено в описании Объекта operations в Шаге 4: Объект paths.
Добавим приведенный выше код к корневому уровню документа OpenAPI в интерфейсе Swagger.
В Swagger UI после описания API появится ссылка вместе с информацией об API:
Ссылка на внешнюю документацию
На данный момент, мы можем догадаться о некоторых проблемам интеграции Swagger UI с остальной частью нашей документации. Скорее всего, будет два вывода и полуфрагментированный пользовательский опыт. Объект externalDocs обеспечивает предсказуемое место для ссылки концептуальных разделов. См. Интеграция Swagger UI со сторонними документами для получения дополнительной информации о стратегиях интеграции.
Теперь, когда мы выполнили все шаги в руководстве OpenAPI, мы закончили создание нашего документа спецификации OpenAPI. Итоговый вариант спецификации здесь: https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml
Вот как выглядит собранная в Swagger UI спецификация:
