Този пост беше последно редактиран от 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 endpoint, за да се разкрие автоматично Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Вградена версия на UI инструмента Swagger. Той интерпретира Swagger JSON, за да създава персонализируеми, богати преживявания, които описват функционалността на уеб API-тата. Включва вградени инструменти за тестване на често срещани методи.
Как да инсталирам Swashbuckle с VS2017?
Първият начин: инсталирай от прозореца на конзолата на Package Manager
- Отидете в Views > Other Windows > Package Manager Console
- Навигирайте до директорията, която съдържа файла TodoApi.csproj
- Моля, изпълнете следната команда · Install-Package Swashbuckle.AspNetCore
-
Втори начин: От диалога Manage NuGet Packages:- Кликнете с десен бутон върху проекта в Solution Explorer > Manage NuGet Packages
- Задайте Package Source на nuget.org
- Въведете "Swashbuckle.AspNetCore" в полето за търсене
- Изберете пакета Swashbuckle.AspNetCore от таба Browse и кликнете върху Инсталиране
-
Добавете и конфигурирайте междинния софтуер SwaggerПърво въведете пространството от имена: Добавете генератора на Swagger към колекцията от услуги в метода Startup.ConfigureServices: вСтартирай.Конфигурирайметод, позволява на междинния софтуер да обслужва генерирания JSON документ и Swagger UI:
Стартирай приложението и навигирай до негоhttps://localhost:<port>/swagger/v1/swagger.json。 Получената документация, описваща крайната точка, се показва в JSON формат, както следва.
Наличниhttps://localhost:<port>/swaggerНамерете Swagger UI. Разгледайте API документацията през интерфейса на Swagger, както е показано по-долу.
За да се приложи коренът (http://localhost:<port>/) за да предоставите Swagger UI, моля, поставетеМаршрутен префиксСвойството се задава на празен низ:
Разширена употреба на Swagger (персонализация и разширения)Използвайте Swagger, за да добавите обяснителна информация към документацията на APIСледните конфигурационни операции се извършват в метода AddSwaggerGen, който добавя информация като автор, лиценз и описание: Информацията за версията на wagger UI е показана на следната фигура: Добавете коментари към интерфейсните методиНека първо кликнем върху API-то, да разширим както е показано на фигурата по-долу, може ли да няма коментари, как да добавим коментари? Добавете коментари към документа с три/както е показано на изображението по-долу, както е показано по-долу След това стартирай проекта и се върни в swaggerUI, за да видиш дали коментарът ще се появи Пак не се появи, не се притеснявай, погледни надолу! Активиране на XML анотацииМожете да активирате XML анотации чрез следните методи: - Кликнете с десен бутон върху проекта в Solution Explorer и изберете Свойства
- Погледнете полето XML Document File в секцията Output на таба Build
-
Включването на XML анотации предоставя информация за дебъгване на недокументирани общи типове и членове. Ако се появят много предупредителни съобщения, например, следното съобщение показва нарушение на предупредителен код 1591:
Ами ако имаш ОКР и искаш да отмениш предупреждението? Можете да анулирате, както е показано на изображението по-долу
Обърнете внимание на пътя на xml документния файл, генериран по-горе,
Бележка: 1. За Linux или не-Windows операционни системи, имената и пътищата на файловете са чувствителни към регистри. Например, "SwaggerDemo.xml" файл работи на Windows, но не и на CentOS. 2. За да получите пътя на приложението, се препоръчва да се използва AppContext.BaseDirectory Преизградете и стартирайте проекта, за да видите дали ще се появят коментарите От горната операция може да се обобщи, че UI на Swagger показва <summary> вътрешния текст на елементите на горния код за коментари като големи коментари в API! Разбира се, можете също да добавите елемента с забележки към документацията Get How-to. Той може да допълни <summary> информацията, посочена в елемента, и да осигури по-надежден Swagger UI. <remarks> Съдържанието на елемента може да съдържа текст, JSON или XML. Кодът е следният: Тествайте API интерфейса с SwaggerUIНека дебъгваме интерфейса чрез SwaggerUI чрез малък пример
- Кликнете върху API интерфейс, който трябва да бъде тестван, и след това натиснете бутона "Пробвай го" вляво и вдясно на Parameters
- Въведете параметър в текстовото поле за параметъра, който се появява, както е показано на следващото изображение, въведете параметър 2
- Кликнете върху бутона Execute и форматираният отговор, показан по-долу, ще се появи, както е показано на фигурата по-долу
Е, това е всичко за днешния урок за използване на 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 ч.
|
|
|
|
