Denne artikkelen er en speilartikkel om maskinoversettelse, vennligst klikk her for å hoppe til originalartikkelen.

Architect_Programmer_Code Landbruksnettverket»Arkitekt › Programmering › .Net/C # › ASP.NET Core WebApi bruker Swagger for å generere API-dokumentasjon ...
Utsikt: 18168|Svare: 0

[.NET Core] ASP.NET Core WebAPI bruker Swagger for å generere API-dokumentasjon

[Kopier lenke]
Publisert på 12.04.2019 14:14:46 | | | |
Dette innlegget ble sist redigert av QWERTYU 12.04.2019 kl. 14:24

Introduksjon
Etter å ha brukt asp.net Core til API-utvikling, må det være en krevende oppgave for programmerere å skrive API-dokumentasjon, men dokumentasjonen må skrives, og hvis det ikke er spesifikke krav til dokumentasjonsformatet, avhenger den endelige dokumentasjonen helt av utviklerens humør. Eller vær mer detaljert, eller enklere. Så finnes det en rask og effektiv måte å bygge API-dokumentasjon på? Svaret er ja, Swagger er et av de mest populære dokumentasjonsverktøyene for REST API-er!
Hvorfor bruke Swagger som et dokumentasjonsverktøy for REST API-er
  • Swagger kan generere en interaktiv API-konsoll som utviklere kan bruke til raskt å lære og eksperimentere med API-er.
  • Swagger kan generere klient-SDK-kode for implementasjoner på ulike plattformer.
  • Swagger-filer kan automatisk genereres fra kodekommentarer på mange forskjellige plattformer.
  • Swagger har et sterkt fellesskap med mange sterke bidragsytere.
Hvordan bruke Swagger til å generere API-dokumentasjon i asp.net kjerne?
  • Swashbuckle.AspNetCore er et åpen kildekode-prosjekt som genererer Swagger-dokumentasjon for ASP.NET Core Web API.
  • NSwag er et annet åpen kildekode-prosjekt for å integrere Swagger UI eller ReDoc i ASP.NET Core Web API-er. Den gir en måte å generere C#- og TypeScript-klientkode for API-er.
Følgende er et eksempel på Swashbuckle.AspNetCoreHva er komponentene i en Swashbuckle?
  • Swashbuckle.AspNetCore.Swagger: Eksponerer SwaggerDocument-objektet som en Swagger-objektmodell og mellomvare for JSON-endepunkter.
  • Swashbuckle.AspNetCore.SwaggerGen: En Swagger-generator som genererer SwaggerDocument-objekter direkte fra ruter, kontrollere og modeller. Det kombineres ofte med Swagger endpoint-mellomvare for automatisk å eksponere Swagger JSON.
  • Swashbuckle.AspNetCore.SwaggerUI: En innebygd versjon av Swagger UI-verktøyet. Den tolker Swagger JSON for å bygge tilpassbare, rike opplevelser som beskriver funksjonaliteten til web-API-er. Den inkluderer innebygde testverktøy for vanlige metoder.
Hvordan installere Swashbuckle med vs2017?

Den første måten: installer fra Package Manager-konsollvinduet



    • Gå til visninger > andre Windows > pakkehåndteringskonsoll
    • Naviger til mappen som inneholder TodoApi.csproj-filen
    • Vennligst utfør følgende kommando · Install-Package Swashbuckle.AspNetCore





Andre måte: Fra dialogen Administrer NuGet Packages:
  • Høyreklikk på prosjektet i Løsningsutforsker > Administrer NuGet-pakker
  • Sett pakkekilde til nuget.org
  • Skriv "Swashbuckle.AspNetCore" i søkefeltet
  • Velg Swashbuckle.AspNetCore-pakken fra fanen Bla gjennom og klikk på Installer

Legg til og konfigurer Swagger-mellomvare
Introduser navnerommet først:
Legg til Swagger-generatoren i tjenestesamlingen i Startup.ConfigureServices-metoden:
påStartup.Configuremetode, aktivere mellomvare for å levere det genererte JSON-dokumentet og Swagger UI:

Start appen og naviger til denhttps://localhost:<port>/swagger/v1/swagger.json。 Den resulterende dokumentasjonen som beskriver endepunktet vises i JSON-format som følger.

Tilgjengelighttps://localhost:<port>/swaggerFinn Swagger-grensesnittet. Bla gjennom API-dokumentasjonen via Swagger-grensesnittet som vist nedenfor.

For å anvende roten (http://localhost:<port>/) for å tilby Swagger-grensesnittet, vennligst legg tilRutePrefiksEgenskapen settes til en tom streng:
Avansert bruk av Swagger (tilpasning og utvidelser)Bruk Swagger for å legge til forklarende informasjon i API-dokumentasjonen
Følgende konfigurasjonsoperasjoner utføres i AddSwaggerGen-metoden, som legger til informasjon som forfatter, lisens og beskrivelse:
Informasjonen om wagger UI-visningsversjonen vises i følgende figur:
Legg til kommentarer til grensesnittmetoder
La oss klikke på API-et først, utvide som vist i figuren under, kan det ikke være kommentarer, hvordan legger man til kommentarer?
Legg til dokumentkommentarer med tre/som vist på bildet under, som vist nedenfor
Kjør deretter prosjektet og gå tilbake til swaggerUI for å se om kommentaren dukker opp
Den dukket fortsatt ikke opp, ikke bekymre deg, se ned!
Aktiver XML-annotasjoner
Du kan aktivere XML-annotasjoner ved hjelp av følgende metoder:
  • Høyreklikk på prosjektet i Løsningsutforsker og velg Egenskaper
  • Se på XML-dokumentfil-boksen under Utdata-seksjonen i Bygg-fanen




Aktivering av XML-annotasjoner gir feilsøkingsinformasjon for udokumenterte vanlige typer og medlemmer. Hvis mange advarselsmeldinger vises, indikerer følgende melding et brudd på advarselskode 1591:
Hva om du har OCD og ønsker å avbryte advarselen? Du kan kansellere som vist på bildet under

Legg merke til stien til xml-dokumentfilen generert ovenfor,
Notat:
1. For Linux- eller ikke-Windows-operativsystemer er filnavn og stier små og mellombokstaver. For eksempel fungerer en "SwaggerDemo.xml"-fil på Windows, men ikke på CentOS.
2. For å hente applikasjonsstien anbefales det å bruke AppContext.BaseDirectory for å hente den
Bygg opp og kjør prosjektet på nytt for å se om kommentarene dukker opp
Ut fra denne operasjonen kan det oppsummeres at Swagger-grensesnittet viser den <summary> interne teksten til elementene i kommentarkoden ovenfor som API-store kommentarer!
Selvfølgelig kan du også legge til kommentar-elementet i Hent veiledningsdokumentasjonen. Den kan <summary> supplere informasjonen som er spesifisert i elementet og gi et mer pålitelig Swagger-grensesnitt. <remarks> Elementinnhold kan inneholde tekst, JSON eller XML. Koden er som følger:
Test API-grensesnittet med SwaggerUI
La oss feilsøke grensesnittet gjennom SwaggerUI med et lite eksempel
  • Klikk på et API-grensesnitt som må testes, og klikk deretter på «Prøv det ut»-knappen til venstre og høyre for Parameters
  • Skriv inn en parameter i parametertekstboksen som vises, som vist i bildet nedenfor, og skriv inn parameter 2
  • Klikk på Utfør-knappen, og det formaterte svaret vist nedenfor vises, som vist i figuren under


Vel, det var alt for dagens veiledning om å bruke Swagger for å generere API-dokumentasjon i ASP.NET Core WebApi. Jeg håper det vil være nyttig for deg å lære hvordan du bruker Swagger til å generere API-dokumentasjon i ASP.NET Core!
sammendrag
Denne artikkelen starter med problemet med å skrive API-dokumentasjon for hånd, og leder deretter til Swagger, et verktøy som automatisk genererer API-dokumentasjon! Deretter, gjennom lettfattelig tekst og bilder, vil vi demonstrere hvordan man bruker SwaggerUI til å generere API-dokumentasjon i en ASP.NET Core WebApi. Til slutt vil jeg introdusere noen avanserte bruksområder for Swagger i ASP.NET Core! Jeg håper det hjelper deg å bruke Swagger i ASP.NET Core!







Foregående:asp.net GridView genererer dynamisk kolonner
Neste:Tilpasning av ModelBinder-metoden for kompatible formstrenger
Ansvarsfraskrivelse:
All programvare, programmeringsmateriell eller artikler publisert av Code Farmer Network er kun for lærings- og forskningsformål; Innholdet ovenfor skal ikke brukes til kommersielle eller ulovlige formål, ellers skal brukerne bære alle konsekvenser. Informasjonen på dette nettstedet kommer fra Internett, og opphavsrettstvister har ingenting med dette nettstedet å gjøre. Du må fullstendig slette innholdet ovenfor fra datamaskinen din innen 24 timer etter nedlasting. Hvis du liker programmet, vennligst støtt ekte programvare, kjøp registrering, og få bedre ekte tjenester. Hvis det foreligger noen krenkelse, vennligst kontakt oss på e-post.
Mail To:help@itsvse.com