ASP.NET Core WebApi käyttää Swaggeria API-dokumentaation tuottamiseen

QWERTYU · Julkaistu 12.4.2019 14.14.46

Tätä julkaisua on viimeksi muokannut QWERTYU 2019-4-12 klo 14:24

Johdanto

asp.net Coren käytön jälkeen API-kehityksessä API-dokumentaation kirjoittaminen on varmasti kivulias tehtävä ohjelmoijille, mutta dokumentaatio on kirjoitettava, ja jos dokumentaation formaatille ei ole erityisiä vaatimuksia, lopullinen dokumentaatio riippuu täysin kehittäjän mielialasta. Tai olla yksityiskohtaisempi tai yksinkertaisempi. Onko siis olemassa nopeaa ja tehokasta tapaa rakentaa API-dokumentaatiota? Vastaus on kyllä, Swagger on yksi suosituimmista REST API:n dokumentaation generointityökaluista!

Miksi käyttää Swaggeria REST API:n dokumentaation generointityökaluna

Swagger voi luoda interaktiivisen API-konsolin, jonka avulla kehittäjät voivat oppia ja kokeilla API-rajapintoja nopeasti.
Swagger voi tuottaa asiakas-SDK-koodia toteutuksiin monilla eri alustoilla.
Swagger-tiedostoja voidaan automaattisesti luoda koodikommenteista monilla eri alustoilla.
Swaggerilla on vahva yhteisö, jossa on paljon vahvoja osallistujia.

Kuinka käyttää Swaggeria API-dokumentaation tuottamiseen asp.net ytimessä?

Swashbuckle.AspNetCore on avoimen lähdekoodin projekti, joka tuottaa Swagger-dokumentaatiota ASP.NET Core Web API:lle.
NSwag on toinen avoimen lähdekoodin projekti, joka integroi Swagger UI:n tai ReDocin ASP.NET Core Web API:iin. Se tarjoaa tavan generoida C#- ja TypeScript-asiakaskoodia API-rajapinnoille.

Seuraava on esimerkki Swashbuckle.AspNetCore-palvelustaMitkä ovat Swashbucklen osat?

Swashbuckle.AspNetCore.Swagger: Paljastaa SwaggerDocument-objektin Swagger-objektimallina ja väliohjelmistona JSON-päätepisteille.
Swashbuckle.AspNetCore.SwaggerGen: Swagger-generaattori, joka generoi SwaggerDocument-objekteja suoraan reiteistä, ohjaimista ja malleista. Se yhdistetään usein Swaggerin päätelaitteiden middlewareen automaattisesti Swagger JSONin paljastamiseksi.
Swashbuckle.AspNetCore.SwaggerUI: Swagger UI -työkalun upotettu versio. Se tulkitsee Swagger JSONia luodakseen räätälöitäviä, rikkaita kokemuksia, jotka kuvaavat Web-API:ien toiminnallisuutta. Se sisältää sisäänrakennetut testaustyökalut yleisille menetelmille.

Kuinka asentaa Swashbuckle vs2017:n kanssa?

Ensimmäinen tapa: asenna Package Manager Console -ikkunasta

Mene Views > muihin Windows > Package Manager -konsoleihin
Siirry hakemistoon, joka sisältää TodoApi.cspoj-tiedoston
Suorita seuraava käsky · Install-Package Swashbuckle.AspNetCore

Toinen tapa: Manage NuGet Packages -dialokista:

Napsauta projektia hiiren oikealla Solution Exploressa > Manage NuGet-paketteja
Aseta paketin lähdekoodiksi nuget.org
Kirjoita hakukenttään "Swashbuckle.AspNetCore"
Valitse Selaa-välilehdeltä Swashbuckle.AspNetCore -paketti ja klikkaa Asenna

Lisää ja konfiguroi Swagger-middleware

Esittele nimiavaruus ensin:

Kirjautuminen näkyy.

Lisää Swagger-generaattori palvelukokoelmaan Startup.ConfigureServices-metodissa:

Kirjautuminen näkyy.

AtStartup.Configuremetodi, mahdollista middleware palvelemaan luotua JSON-dokumenttia ja Swagger-käyttöliittymää:

Kirjautuminen näkyy.

Käynnistä sovellus ja siirry siihenhttps://localhost:<port>/swagger/v1/swagger.json。 Tuloksena saatu dokumentaatio, joka kuvaa päätepistettä, esitetään JSON-muodossa seuraavasti.

Saatavillahttps://localhost:<port>/itsevarmuusEtsi Swaggerin käyttöliittymä. Selaa API-dokumentaatiota Swaggerin käyttöliittymän kautta, kuten alla on esitetty.

Juuren soveltamiseksi (http://localhost:<port>/) tarjotaksesi Swagger-käyttöliittymän, laitaReittietuliiteOminaisuus asetetaan tyhjäksi merkkijonoksi:

Kirjautuminen näkyy.

Swaggerin edistynyt käyttö (muokkaus ja laajennukset)Käytä Swaggeria lisätäksesi selittävää tietoa API-dokumentaatioon

Seuraavat konfigurointitoiminnot suoritetaan AddSwaggerGen-menetelmällä, joka lisää tietoja, kuten tekijä-, lisenssi- ja kuvaustiedot:

Kirjautuminen näkyy.

Wagger-käyttöliittymän näyttöversion tiedot on esitetty seuraavassa kuvassa:

Lisää kommentteja rajapintametodeihin

Klikkataan ensin API:a, laajennetaan kuten alla olevassa kuvassa näkyy, eikö kommentteja tule, miten kommentteja lisätään?

Lisää dokumenttikommentit kolmella/kuten alla olevassa kuvassa, kuten alla on

Kirjautuminen näkyy.

Sitten käynnistä projekti ja palaa swaggerUI:hin nähdäksesi, ilmestyykö kommentti

Ei vieläkään ilmestynyt, älä huoli, katso alas!

Ota XML-merkinnät käyttöön

Voit ottaa XML-annotaatiot käyttöön seuraavilla menetelmillä:

Napsauta projektia oikealla Ratkaisunhallinnassa ja valitse Ominaisuudet
Katso XML Document File -kenttää Build-välilehden Output-osiossa

XML-merkintöjen käyttöönotto tarjoaa virheenkorjaustietoa dokumentoimattomille yleisille tyypeille ja jäsenille. Jos varoitusviestejä ilmestyy paljon, esimerkiksi seuraava viesti viittaa varoituskoodin 1591 rikkomiseen:

Kirjautuminen näkyy.

Entä jos sinulla on pakko-oireinen häiriö ja haluat peruuttaa varoituksen? Voit peruuttaa, kuten alla olevassa kuvassa näkyy.

Huomaa yllä luodun xml-dokumenttitiedoston polku,

Muistiinpano:

1. Linux- tai ei-Windows-käyttöjärjestelmissä tiedostonimet ja polut ovat kirjainkoon herkkiä. Esimerkiksi "SwaggerDemo.xml"-tiedosto toimii Windowsissa, mutta ei CentOS:ssa.

2. Sovelluspolun saamiseksi suositellaan käyttämään AppContext.BaseDirectorya sen saamiseksi

Kirjautuminen näkyy.

Rakenna uudelleen ja aja projekti nähdäksesi, näkyvätkö kommentit

Yllä olevasta operaatiosta voidaan tiivistää, että Swaggerin käyttöliittymä näyttää <summary> yllä olevan kommenttikoodin elementtien sisäiset tekstit API-suurina kommentteina!

Tietenkin voit myös lisätä huomautuselementin Hake-ohje-dokumentaatioon. Se voi <summary> täydentää elementissä määriteltyjä tietoja ja tarjota luotettavamman Swagger-käyttöliittymän. <remarks> Elementtisisältö voi sisältää tekstiä, JSONia tai XML:ää. Koodi on seuraava:

Kirjautuminen näkyy.

Testaa API-rajapintaa SwaggerUI:lla

Debuggataanpa käyttöliittymä SwaggerUI:n kautta pienen esimerkin kautta

Klikkaa API-rajapintaa, joka täytyy testata, ja valitse sitten "Try it out" -painiketta Parametrien vasemmalla ja oikealla puolella
Syötä parametrin tekstilaatikkoon, joka ilmestyy, kuten seuraavassa kuvassa näkyy, syötä parametri 2
Klikkaa Suorita-painiketta, niin alla oleva muotoiltu vastaus ilmestyy, kuten alla olevassa kuvassa on esitetty

No, siinä oli tämän päivän opetus Swaggerin käytöstä API-dokumentaation luomiseen ASP.NET Core WebApissa. Toivon, että on hyödyllistä oppia käyttämään Swaggeria API-dokumentaation tuottamiseen ASP.NET Coressa!

yhteenveto

Tämä artikkeli alkaa API-dokumentaation käsin kirjoittamisen kipupisteestä ja johtaa sitten Swaggeriin, työkaluun, joka automaattisesti tuottaa API-dokumentaatiota! Sen jälkeen näytämme helposti ymmärrettävän tekstin ja kuvien avulla, miten SwaggerUI:ta käytetään API-dokumentaation tuottamiseen ASP.NET Core WebApissa. Lopuksi esittelen joitakin edistyneitä Swaggerin käyttötapoja ASP.NET Coressa! Toivottavasti se auttaa sinua käyttämään Swaggeria ASP.NET Coressa!

[.NET Core] ASP.NET Core WebApi käyttää Swaggeria API-dokumentaation tuottamiseen

Katsotut osuudet