Dette indlæg blev sidst redigeret af QWERTYU den 12-4-2019 kl. 14:24
IndførelsenEfter at have brugt asp.net Core til API-udvikling, må det være en besværlig opgave for programmører at skrive API-dokumentation, men dokumentationen skal skrives, og hvis der ikke er specifikke krav til dokumentationens format, afhænger den endelige dokumentation fuldstændigt af udviklerens humør. Eller vær mere detaljeret, eller enklere. Så findes der en hurtig og effektiv måde at bygge API-dokumentation på? Svaret er ja, Swagger er et af de mest populære værktøjer til dokumentationsgenerering af REST API'er!
Hvorfor bruge Swagger som et værktøj til dokumentationsgenerering af REST API'er- Swagger kan generere en interaktiv API-konsol, som udviklere kan bruge til hurtigt at lære og eksperimentere med API'er.
- Swagger kan generere klient-SDK-kode til implementeringer på en række forskellige platforme.
- Swagger-filer kan automatisk genereres ud fra kodekommentarer på mange forskellige platforme.
- Swagger har et stærkt fællesskab med mange stærke bidragydere.
Hvordan bruger man Swagger til at generere API-dokumentation i asp.net kerne?- Swashbuckle.AspNetCore er et open source-projekt, der genererer Swagger-dokumentation til ASP.NET Core Web API.
- NSwag er et andet open source-projekt til integration af Swagger UI eller ReDoc i ASP.NET Core Web API'er. Det giver en måde at generere C#- og TypeScript-klientkode til API'er.
Følgende er et eksempel på Swashbuckle.AspNetCoreHvad er komponenterne i en Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Eksponerer SwaggerDocument-objektet som en Swagger-objektmodel og middleware til JSON-endpoints.
- Swashbuckle.AspNetCore.SwaggerGen: En Swagger-generator, der genererer SwaggerDocument-objekter direkte fra ruter, controllere og modeller. Det kombineres ofte med Swagger endpoint middleware for automatisk at eksponere Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: En indlejret version af Swagger UI-værktøjet. Den fortolker Swagger JSON til at bygge tilpasselige, rige oplevelser, der beskriver funktionaliteten af web-API'er. Den inkluderer indbyggede testværktøjer til almindelige metoder.
Hvordan installerer man Swashbuckle med VS2017?
Den første måde: installer fra Package Manager-konsolvinduet
- Gå til Visninger > andre Windows-> pakkehåndteringskonsollen
- Navigér til mappen, der indeholder TodoApi.csproj-filen
- Venligst udfør følgende kommando · Install-Package Swashbuckle.AspNetCore
-
Anden måde: Fra dialogen Administrer NuGet Pakker:- Højreklik på projektet i Solution Explorer > Administrer NuGet-pakker
- Sæt pakkekilde til nuget.org
- Indtast "Swashbuckle.AspNetCore" i søgefeltet
- Vælg Swashbuckle.AspNetCore-pakken fra fanen Gennemse og klik på Installer
-
Tilføj og konfigurér Swagger-middlewareIntroducer navnerummet først: Tilføj Swagger-generatoren til servicesamlingen i Startup.ConfigureServices-metoden: vedStartup.Configuremetode, gør middleware tilgængelig for at levere det genererede JSON-dokument og Swagger UI:
Start appen og naviger til denhttps://localhost:<port>/swagger/v1/swagger.json。 Den resulterende dokumentation, der beskriver endepunktet, vises i JSON-format som følger.
Tilgængelighttps://localhost:<port>/swaggerFind Swagger-brugerfladen. Gennemse API-dokumentationen via Swagger UI som vist nedenfor.
For at anvende roden (http://localhost:<port>/) for at levere Swagger-brugerfladen, sæt venligstRutepræfiksEgenskaben sættes til en tom streng:
Avanceret brug af Swagger (Tilpasning og udvidelser)Brug Swagger til at tilføje forklarende information til API-dokumentationenFølgende konfigurationsoperationer udføres i AddSwaggerGen-metoden, som tilføjer information såsom forfatter-, licens- og beskrivelsesinformation: Oplysningerne om wagger UI-visningsversionen vises i følgende figur: Tilføj kommentarer til interface-metoderLad os klikke på API'en først, udvide som vist i figuren nedenfor, kan der ikke være kommentarer, hvordan tilføjer man kommentarer? Tilføj dokumentkommentarer med tre/som vist på billedet nedenfor, som vist nedenfor Kør derefter projektet og gå tilbage til swaggerUI for at se, om kommentaren dukker op Den dukkede stadig ikke op, bare rolig, kig ned! Aktivér XML-annoteringerDu kan aktivere XML-annoteringer ved hjælp af følgende metoder: - Højreklik på projektet i Solution Explorer og vælg Egenskaber
- Se på XML-dokumentfilboksen under Output-sektionen i fanen Byg
-
Aktivering af XML-annoteringer giver fejlsøgningsinformation for udokumenterede almindelige typer og medlemmer. Hvis der for eksempel vises mange advarselsmeddelelser, indikerer følgende meddelelse en overtrædelse af advarselskode 1591:
Hvad hvis du har OCD og vil annullere advarslen? Du kan annullere, som vist på billedet nedenfor
Bemærk stien for xml-dokumentfilen, der blev genereret ovenfor,
Seddel: 1. For Linux- eller ikke-Windows-operativsystemer er filnavne og stier små og små bogstaver. For eksempel virker en "SwaggerDemo.xml"-fil på Windows, men ikke på CentOS. 2. For at hente applikationsstien anbefales det at bruge AppContext.BaseDirectory til at hente den Genopbyg og kør projektet for at se, om kommentarerne dukker op Ud fra ovenstående operation kan det opsummeres, at Swagger UI viser den <summary> interne tekst af elementerne i ovenstående kommentarkode som API-store kommentarer! Selvfølgelig kan du også tilføje kommentarelementet til Hent vejledningsdokumentationen. Den kan <summary> supplere de oplysninger, der er angivet i elementet, og give en mere pålidelig Swagger-brugerflade. <remarks> Elementindhold kan indeholde tekst, JSON eller XML. Koden er som følger: Test API-grænsefladen med SwaggerUILad os fejlfinde grænsefladen via SwaggerUI med et lille eksempel
- Klik på et API-interface, der skal testes, og klik derefter på knappen "Prøv det ud" til venstre og højre for Parameters
- Indtast en parameter i parametertekstboksen, der vises, som vist på det følgende billede, og indtast parameter 2
- Klik på Udfør-knappen, og det formaterede svar vist nedenfor vil vises, som vist i figuren nedenfor
Nå, det var det for dagens vejledning om at bruge Swagger til at generere API-dokumentation i ASP.NET Core WebApi. Jeg håber, det vil være nyttigt for dig at lære, hvordan du bruger Swagger til at generere API-dokumentation i ASP.NET Core! resuméDenne artikel starter med det smertefulde punkt ved at skrive API-dokumentation i hånden og fører derefter til Swagger, et værktøj der automatisk genererer API-dokumentation! Derefter vil vi gennem letforståelig tekst og billeder demonstrere, hvordan man bruger SwaggerUI til at generere API-dokumentation i en ASP.NET Core WebApi. Endelig vil jeg introducere nogle avancerede anvendelser af Swagger i ASP.NET Core! Jeg håber, det hjælper dig med at bruge Swagger i ASP.NET Core!
| 
Opslået på 12/04/2019 14.14.46
|
|
|
|
