Detta inlägg redigerades senast av QWERTYU den 2019-4-12 14:24
InförandetEfter att ha använt asp.net Core för API-utveckling måste det vara en besvärlig uppgift för programmerare att skriva API-dokumentation, men dokumentationen måste skrivas, och om det inte finns några specifika krav på dokumentationens format beror den slutliga dokumentationen helt på utvecklarens humör. Eller var mer detaljerad, eller enklare. Så finns det ett snabbt och effektivt sätt att bygga API-dokumentation? Svaret är ja, Swagger är ett av de mest populära verktygen för dokumentationsgenerering av REST API:er!
Varför använda Swagger som ett verktyg för dokumentationsgenerering av REST API:er- Swagger kan generera en interaktiv API-konsol som utvecklare kan använda för att snabbt lära sig och experimentera med API:er.
- Swagger kan generera klient-SDK-kod för implementationer på en rad olika plattformar.
- Swagger-filer kan automatiskt genereras från kodkommentarer på många olika plattformar.
- Swagger har en stark gemenskap med många starka bidragsgivare.
Hur använder man Swagger för att generera API-dokumentation i asp.net kärna?- Swashbuckle.AspNetCore är ett öppen källkodsprojekt som genererar Swagger-dokumentation för ASP.NET Core Web API.
- NSwag är ett annat open source-projekt för att integrera Swagger UI eller ReDoc i ASP.NET Core Web API:er. Det ger ett sätt att generera C#- och TypeScript-klientkod för API:er.
Följande är ett exempel på Swashbuckle.AspNetCoreVilka är komponenterna i en Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Exponerar objektet SwaggerDocument som en Swagger-objektmodell och middleware för JSON-endpoints.
- Swashbuckle.AspNetCore.SwaggerGen: En Swagger-generator som genererar SwaggerDokument-objekt direkt från rutter, kontroller och modeller. Den kombineras ofta med Swagger endpoint-middleware för att automatiskt exponera Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: En inbäddad version av Swagger UI-verktyget. Den tolkar Swagger JSON för att bygga anpassningsbara, rika upplevelser som beskriver funktionaliteten hos webb-API:er. Den inkluderar inbyggda testverktyg för vanliga metoder.
Hur installerar man Swashbuckle med vs2017?
Det första sättet: installera från Package Manager-konsolfönstret
- Gå till vyer > andra Windows > Package Manager Console
- Gå till katalogen som innehåller filen TodoApi.csproj
- Var vänlig utför följande kommando · Install-Package Swashbuckle.AspNetCore
-
Andra sättet: Från dialogen Hantera NuGet Packages:- Högerklicka på projektet i Solution Explorer > Hantera NuGet-paket
- Ställ in paketkällan till nuget.org
- Skriv "Swashbuckle.AspNetCore" i sökrutan
- Välj Swashbuckle.AspNetCore-paketet från fliken Bläddra och klicka på Installera
-
Lägg till och konfigurera Swagger-middlewareIntroducera namnrymden först: Lägg till Swagger-generatorn i tjänstesamlingen i Startup.ConfigureServices-metoden: vidStartup.Konfigurerametoden, aktivera middleware för att leverera det genererade JSON-dokumentet och Swagger UI:
Starta appen och navigera till denhttps://localhost:<port>/swagger/v1/swagger.json。 Den resulterande dokumentationen som beskriver slutpunkten visas i JSON-format enligt följande.
Tillgänglighttps://localhost:<port>/swaggerHitta Swagger-gränssnittet. Bläddra i API-dokumentationen via Swagger UI som visas nedan.
För att tillämpa roten (http://localhost:<port>/) för att tillhandahålla Swagger-gränssnittet, vänligen skriv inRuttPrefixEgenskapen sätts till en tom sträng:
Avancerad användning av Swagger (anpassning och tillägg)Använd Swagger för att lägga till förklarande information i API-dokumentationenFöljande konfigurationsoperationer utförs i AddSwaggerGen-metoden, som lägger till information såsom författare, licens och beskrivningsinformation: Informationen om wagger UI-visningsversionen visas i följande figur: Lägg till kommentarer till gränssnittsmetoderLåt oss klicka på API:et först, expandera som visas i figuren nedan, kan det inte finnas några kommentarer, hur lägger man till kommentarer? Lägg till dokumentkommentarer med tre/som visas på bilden nedan, som visas nedan Kör sedan projektet och gå tillbaka till swaggerUI för att se om kommentaren dyker upp Den dök fortfarande inte upp, oroa dig inte, titta ner! Aktivera XML-annotationerDu kan aktivera XML-anteckningar med följande metoder: - Högerklicka på projektet i Lösningsutforskaren och välj Egenskaper
- Titta på rutan XML Document File under avsnittet Output i fliken Bygg
-
Aktivering av XML-annoteringar ger felsökningsinformation för odokumenterade vanliga typer och medlemmar. Om många varningsmeddelanden förekommer, till exempel, indikerar följande meddelande ett brott mot varningskod 1591:
Vad händer om du har OCD och vill avbryta varningen? Du kan avbryta som visas på bilden nedan
Notera sökvägen för xml-dokumentfilen som genererades ovan,
Not: 1. För Linux- eller icke-Windows-operativsystem är filnamn och sökvägar kasuskänsliga. Till exempel fungerar en "SwaggerDemo.xml"-fil på Windows, men inte på CentOS. 2. För att hämta applikationssökvägen rekommenderas det att använda AppContext.BaseDirectory för att hämta den Bygg om och kör projektet för att se om kommentarerna dyker upp Utifrån ovanstående operation kan det sammanfattas att Swagger-gränssnittet visar den <summary> interna texten i elementen i kommentarkoden ovan som API-stora kommentarer! Självklart kan du också lägga till kommentarselementet i Hämta instruktionsdokumentationen. Den kan <summary> komplettera informationen som anges i elementet och erbjuda ett mer pålitligt Swagger-gränssnitt. <remarks> Elementinnehåll kan innehålla text, JSON eller XML. Koden är följande: Testa API-gränssnittet med SwaggerUILåt oss felsöka gränssnittet via SwaggerUI med ett litet exempel
- Klicka på ett API-gränssnitt som behöver testas, och klicka sedan på knappen "Testa det" till vänster och höger om Parameters
- Ange en parameter i parametertextrutan som visas, som visas i bilden nedan, ange parameter 2
- Klicka på knappen Utför, så visas det formaterade svaret nedan, som visas i figuren nedan
Nåväl, det var allt för dagens handledning om hur man använder Swagger för att generera API-dokumentation i ASP.NET Core WebApi. Jag hoppas att det är till hjälp för dig att lära dig hur man använder Swagger för att generera API-dokumentation i ASP.NET Core! sammanfattningDen här artikeln börjar med smärtpunkten att skriva API-dokumentation för hand, och leder sedan till Swagger, ett verktyg som automatiskt genererar API-dokumentation! Därefter kommer vi, genom lättförståelig text och bilder, att visa hur man använder SwaggerUI för att generera API-dokumentation i en ASP.NET Core WebApi. Slutligen kommer jag att introducera några avancerade användningar av Swagger i ASP.NET Core! Jag hoppas det hjälper dig att använda Swagger i ASP.NET Core!
| 
Publicerad på 2019-04-12 14:14:46
|
|
|
|
