Этот пост был последний раз отредактирован QWERTYU 12.04.2019 14:24
ЗнакомствоПосле использования asp.net Core для разработки API написание документации по API должно быть сложной задачей для программистов, но документация должна быть написана, и если нет конкретных требований к формату документации, итоговая документация полностью зависит от настроения разработчика. Или быть более подробным или проще. Так есть ли быстрый и эффективный способ создать документацию по API? Ответ — да, Swagger — один из самых популярных инструментов для генерации документации REST API!
Зачем использовать Swagger как инструмент генерации документации REST API- Swagger может генерировать интерактивную API-консоль, которую разработчики могут использовать для быстрого изучения и экспериментов с API.
- Swagger может генерировать клиентский SDK-код для реализаций на различных платформах.
- Файлы Swagger можно автоматически генерировать из комментариев кода на различных платформах.
- У Swagger сильное сообщество с множеством активных участников.
Как использовать Swagger для генерации документации API в asp.net ядре?- Swashbuckle.AspNetCore — это проект с открытым исходным кодом, который генерирует документацию Swagger для ASP.NET Core Web API.
- NSwag — ещё один проект с открытым исходным кодом, направленный на интеграцию интерфейса Swagger или ReDoc в ASP.NET API Core Web. Он предоставляет способ генерации клиентского кода на C# и TypeScript для API.
Ниже приведён пример Swashbuckle.AspNetCoreКакие компоненты состоит в Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Открывает объект SwaggerDocument как модель объекта Swagger и промежуточное ПО для JSON-конечных точек.
- Swashbuckle.AspNetCore.SwaggerGen: генератор Swagger, который генерирует объекты SwaggerDocument напрямую из маршрутов, контроллеров и моделей. Часто его комбинируют с промежуточным программным обеспечением Swagger endpoint для автоматического раскрытия Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: встроенная версия инструмента Swagger UI. Он интерпретирует Swagger JSON для создания настраиваемого, насыщенного опыта, описывающего функциональность веб-API. Он включает встроенные инструменты тестирования для распространённых методов.
Как установить Swashbuckle с помощью vs2017?
Первый способ: установка через окно консоли Package Manager
- Перейдите в раздел Views > Other Windows > Package Manager Console
- Перейдите к каталогу, содержащему файл TodoApi.csproj
- Пожалуйста, выполните следующую команду · Install-Package Swashbuckle.AspNetCore
-
Второй способ: из диалога Manage NuGet Packages:- Кликните правой кнопкой мыши по проекту в Solution Explorer > Управление пакетами NuGet
- Установите исходный код пакета на nuget.org
- Введите в поисковую строку «Swashbuckle.AspNetCore»
- Выберите пакет Swashbuckle.AspNetCore на вкладке Browse и нажмите Install
-
Добавить и настроить промежуточное программное обеспечение SwaggerСначала представьте пространство имён: Добавьте генератор Swagger в коллекцию сервисов в методе Startup.ConfigureServices: уStartup.Configureметод, позволяет промежуточному ПО обслуживать сгенерированный JSON-документ и интерфейс Swagger:
Запустите приложение и переходите к немуhttps://localhost:<port>/swagger/v1/swagger.json。 Полученная документация, описывающая конечную точку, отображается в формате JSON следующим образом.
Доступноhttps://localhost:<port>/swaggerНайдите интерфейс Swagger. Просмотрите документацию API через интерфейс Swagger, как показано ниже.
Для нанесения корня (http://localhost:<port>/) чтобы предоставить интерфейс Swagger, пожалуйста, введитеПрефикс маршрутаСвойство задаётся на пустую строку:
Расширенное использование Swagger (кастомизация и расширения)Используйте Swagger для добавления объяснительной информации в документацию APIСледующие операции конфигурации выполняются в методе AddSwaggerGen, который добавляет информацию, такую как автор, лицензия и описание: Информация о версии с интерфейсом wagger отображается на следующем рисунке: Добавляйте комментарии к методам интерфейсаДавайте сначала кликнем на API, расширим, как показано на рисунке ниже, не может ли быть комментариев, как добавить комментарии? Добавьте комментарии к документу с тремя/как показано на изображении ниже, как показано ниже Затем запустите проект и вернитесь в swaggerUI, чтобы посмотреть, появится ли комментарий Всё ещё не появилось, не волнуйся, посмотри вниз! Включить XML-аннотацииВы можете включить XML-аннотации с помощью следующих методов: - Кликните правой кнопкой мыши по проекту в Solution Explorer и выберите Свойства
- Посмотрите поле XML Document File в разделе Output на вкладке Build
-
Включение XML-аннотаций предоставляет отладочную информацию для недокументированных общих типов и членов. Если, например, появляется много предупреждающих сообщений, следующее сообщение указывает на нарушение кода предупреждения 1591:
Что если у вас ОКР, и вы хотите отменить предупреждение? Вы можете отменить, как показано на изображении ниже
Обратите внимание на путь xml-файла, сгенерированного выше,
Заметка: 1. Для Linux или не-Windows имена файлов и пути зависят от регистра. Например, файл «SwaggerDemo.xml» работает в Windows, но не на CentOS. 2. Для получения пути приложения рекомендуется использовать AppContext.BaseDirectory Перестройка и запуск проекта, чтобы посмотреть, появятся ли комментарии Из приведённой выше операции можно резюмировать, что интерфейс Swagger отображает <summary> внутренний текст элементов вышеуказанного кода комментариев в виде больших комментариев в API! Конечно, вы также можете добавить элемент замечаний в документацию Get How-to. Он может дополнить <summary> информацию, указанную в элементе, и обеспечить более надёжный интерфейс Swagger. <remarks> Содержимое элементов может содержать текст, JSON или XML. Код таков: Тестируйте интерфейс API с помощью SwaggerUIДавайте отладим интерфейс через SwaggerUI на небольшом примере
- Кликните на интерфейс API, который нужно протестировать, а затем нажмите кнопку «Попробовать» слева и справа от раздела Параметры
- Введите параметр в текстовое поле параметра, который отображается, как показано на следующем изображении, введите параметр 2
- Нажмите кнопку «Выполнить», и появится отформатированный ответ, показанный ниже, как показано на рисунке ниже
Ну вот, на сегодняшнем уроке по использованию Swagger для генерации документации API в ASP.NET Core WebApi. Надеюсь, вам будет полезно научиться использовать Swagger для генерации документации API в ASP.NET Core! сводкаЭта статья начинается с проблемы написания документации API вручную, а затем переходит к Swagger — инструменту, который автоматически генерирует документацию API! Затем, с помощью понятного текста и картинок, мы продемонстрируем, как использовать SwaggerUI для генерации документации API в ASP.NET Core WebApi. Наконец, я представлю некоторые продвинутые способы использования Swagger в ASP.NET Core! Надеюсь, это поможет вам использовать Swagger в ASP.NET Core!
| 
Опубликовано 12.04.2019 14:14:46
|
|
|
|
