Цей допис востаннє редагувався QWERTYU 2019-4-12 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 UI або ReDoc у ASP.NET Core Web API. Він забезпечує спосіб генерації клієнтського коду C# та TypeScript для API.
Нижче наведено приклад Swashbuckle.AspNetCoreЯкі компоненти складається зі Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Відкриває об'єкт SwaggerDocument як модель об'єкта Swagger та проміжне програмне забезпечення для JSON-кінцевих точок.
- Swashbuckle.AspNetCore.SwaggerGen: Генератор Swagger, який генерує об'єкти SwaggerDocument безпосередньо з маршрутів, контролерів і моделей. Його часто поєднують із проміжним програмним забезпеченням кінцевої точки Swagger для автоматичного відкриття Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: вбудована версія інструменту Swagger UI. Він інтерпретує Swagger JSON для створення налаштовуваних, насичених досвідів, які описують функціональність веб-API. Він містить вбудовані інструменти тестування для поширених методів.
Як встановити Swashbuckle з vs2017?
Перший спосіб: встановлюйте через вікно консолі менеджера пакетів
- Перейдіть до перегляду > інших консолей Windows > Package Manager
- Перейдіть до каталогу, що містить файл TodoApi.csproj
- Будь ласка, виконайте наступну команду · Install-Package Swashbuckle.AspNetCore
-
Другий спосіб: З діалогу «Керувати пакетами NuGet»:- Клацніть правою кнопкою миші по проєкту в Solution Explorer > Керувати пакетами NuGet
- Встановити Package Source на nuget.org
- Введіть у пошуковому рядку "Swashbuckle.AspNetCore"
- Виберіть пакет Swashbuckle.AspNetCore у вкладці Перегляд і натисніть Встановити
-
Додати та налаштувати проміжне програмне забезпечення SwaggerСпочатку введіть простір назв: Додайте генератор Swagger до колекції сервісів у методі Startup.ConfigureServices: приStartup.Configureметод, дозволити middleware обслуговувати згенерований 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> inner text елементів наведеного вище коду коментарів як великі коментарі в 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
|
|
|
|
