Šo ziņu pēdējo reizi rediģēja QWERTYU 2019-4-12 14:24
IevadsPēc asp.net Core izmantošanas API izstrādei API dokumentācijas rakstīšanai jābūt sāpīgam uzdevumam programmētājiem, bet dokumentācija ir jāraksta, un, ja nav īpašu prasību dokumentācijas formātam, galīgā dokumentācija ir pilnībā atkarīga no izstrādātāja noskaņojuma. Vai arī esiet detalizētāks vai vienkāršāks. Tātad, vai ir ātrs un efektīvs veids, kā izveidot API dokumentāciju? Atbilde ir jā, Swagger ir viens no populārākajiem REST API dokumentācijas ģenerēšanas rīkiem!
Kāpēc izmantot Swagger kā REST API dokumentācijas ģenerēšanas rīku- Swagger var ģenerēt interaktīvu API konsoli, ko izstrādātāji var izmantot, lai ātri apgūtu un eksperimentētu ar API.
- Swagger var ģenerēt klienta SDK kodu ieviešanai dažādās platformās.
- Swagger failus var automātiski ģenerēt no koda komentāriem daudzās dažādās platformās.
- Swagger ir spēcīga kopiena ar daudziem spēcīgiem ieguldītājiem.
Kā izmantot Swagger, lai ģenerētu API dokumentāciju asp.net kodolā?- Swashbuckle.AspNetCore ir atvērtā koda projekts, kas ģenerē Swagger dokumentāciju ASP.NET Core Web API.
- NSwag ir vēl viens atvērtā koda projekts Swagger UI vai ReDoc integrēšanai ASP.NET Core Web API. Tas nodrošina veidu, kā ģenerēt C# un TypeScript klienta kodu API.
Tālāk ir sniegts Swashbuckle.AspNetCore piemērsKādas ir Swashbuckle sastāvdaļas?- Swashbuckle.AspNetCore.Swagger: atklāj SwaggerDocument objektu kā Swagger objekta modeli un starpprogrammatūru JSON galapunktiem.
- Swashbuckle.AspNetCore.SwaggerGen: Swagger ģenerators, kas ģenerē SwaggerDocument objektus tieši no maršrutiem, kontrolieriem un modeļiem. To bieži apvieno ar Swagger galapunkta starpprogrammatūru, lai automātiski atklātu Swagger JSON.
- Swashbuckle.AspNetCore.SwaggerUI: Swagger lietotāja interfeisa rīka iegulta versija. Tas interpretē Swagger JSON, lai izveidotu pielāgojamu, bagātīgu pieredzi, kas apraksta Web API funkcionalitāti. Tas ietver iebūvētus testēšanas rīkus kopīgām metodēm.
Kā instalēt Swashbuckle ar vs2017?
Pirmais veids: instalējiet no pakotņu pārvaldnieka konsoles loga
- Dodieties uz Skati > citu Windows > pakotņu pārvaldnieka konsoli
- Naviģējiet uz direktoriju, kurā ir fails TodoApi.csproj
- Lūdzu, izpildiet šādu komandu · Instalēt pakotni Swashbuckle.AspNetCore
-
Otrais veids: No dialoglodziņa Pārvaldīt NuGet pakotnes:- Ar peles labo pogu noklikšķiniet uz projekta risinājumu pārlūkā> pārvaldītu NuGet pakotnes
- Iestatīt pakotnes avotu uz nuget.org
- Meklēšanas lodziņā ierakstiet "Swashbuckle.AspNetCore"
- Cilnē Pārlūkot atlasiet pakotni Swashbuckle.AspNetCore un noklikšķiniet uz Instalēt
-
Swagger starpprogrammatūras pievienošana un konfigurēšanaVispirms iepazīstiniet ar nosaukumvietu: Pievienojiet Swagger ģeneratoru pakalpojumu kolekcijai, izmantojot metodi Startup.ConfigureServices: pieStartēšana.konfigurēšanametodi, iespējojiet starpprogrammatūru, lai apkalpotu ģenerēto JSON dokumentu un Swagger lietotāja interfeisu:
Palaidiet lietotni un dodieties uz tohttps://localhost:<port>/swagger/v1/swagger.json。 Iegūtā dokumentācija, kurā aprakstīts galapunkts, tiek parādīta JSON formātā šādi.
Pieejamshttps://localhost:<port>/swaggerAtrodiet Swagger lietotāja interfeisu. Pārlūkojiet API dokumentāciju, izmantojot Swagger lietotāja interfeisu, kā parādīts tālāk.
Lai lietotu sakni (http://localhost:<port>/), lai nodrošinātu Swagger lietotāja interfeisu, lūdzu, ievietojietRoutePrefixRekvizīts ir iestatīts uz tukšu virkni:
Uzlabota Swagger izmantošana (pielāgošana un paplašinājumi)Izmantojiet Swagger, lai pievienotu paskaidrojošu informāciju API dokumentācijaiAddSwaggerGen metodē tiek veiktas šādas konfigurācijas darbības, kas pievieno informāciju, piemēram, autora, licences un apraksta informāciju: Informācija par wagger lietotāja interfeisa displeja versiju ir parādīta šajā attēlā: Komentāru pievienošana interfeisa metodēmVispirms noklikšķināsim uz API, paplašiniet, kā parādīts zemāk redzamajā attēlā, vai nav komentāru, kā pievienot komentārus? Pievienojiet dokumenta komentārus ar trīs/kā parādīts zemāk redzamajā attēlā, kā parādīts zemāk Pēc tam palaidiet projektu un atgriezieties swaggerUI, lai redzētu, vai tiek parādīts komentārs Joprojām neparādījās, neuztraucieties, paskatieties uz leju! XML anotāciju iespējošanaXML anotācijas var iespējot, izmantojot šādas metodes: - Ar peles labo pogu noklikšķiniet uz projekta risinājumu pārlūkā un atlasiet Rekvizīti
- Apskatiet lodziņu XML dokumenta fails cilnes Veidošana sadaļā Izvade
-
XML anotāciju iespējošana nodrošina atkļūdošanas informāciju par nedokumentētiem vispārējiem tipiem un dalībniekiem. Ja tiek parādīts daudz brīdinājuma ziņojumu, piemēram, šāds ziņojums norāda uz brīdinājuma koda 1591 pārkāpumu:
Ko darīt, ja jums ir OCD un vēlaties atcelt brīdinājumu? Jūs varat atcelt, kā parādīts zemāk redzamajā attēlā
Ņemiet vērā iepriekš ģenerētā xml dokumenta faila ceļu,
Piezīme: 1. Linux vai citām operētājsistēmām failu nosaukumi un ceļi ir reģistrjutīgi. Piemēram, fails "SwaggerDemo.xml" darbojas operētājsistēmā Windows, bet ne CentOS. 2. Lai iegūtu lietojumprogrammas ceļu, ieteicams to iegūt AppContext.BaseDirectory Pārbūvējiet un palaidiet projektu, lai redzētu, vai tiek parādīti komentāri No iepriekš minētās darbības var apkopot, ka Swagger lietotāja saskarne parāda <summary> iepriekš minētā komentāra koda elementu iekšējo tekstu kā API lielus komentārus! Protams, piezīmju elementu var pievienot arī dokumentācijai Iegūt padomus. Tas var papildināt <summary> elementā norādīto informāciju un nodrošināt uzticamāku Swagger lietotāja interfeisu. <remarks> Elementa saturs var saturēt tekstu, JSON vai XML. Kods ir šāds: Pārbaudiet API saskarni, izmantojot SwaggerUIAtkļūdosim saskarni, izmantojot SwaggerUI, izmantojot nelielu piemēru
- Noklikšķiniet uz API saskarnes, kas jāpārbauda, un pēc tam noklikšķiniet uz pogas "Izmēģināt" pa kreisi un pa labi no parametriem
- Ievadiet parametru parādītajā parametru tekstlodziņā, kā parādīts nākamajā attēlā, ievadiet parametru 2
- Noklikšķiniet uz pogas Izpildīt, un parādīsies tālāk redzamā formatētā atbilde, kā parādīts zemāk redzamajā attēlā
Nu, tas ir viss šodienas apmācībai par Swagger izmantošanu, lai ģenerētu API dokumentāciju ASP.NET Core WebApi. Es ceru, ka jums būs noderīgi uzzināt, kā izmantot Swagger, lai ģenerētu API dokumentāciju ASP.NET Core! KopsavilkumaŠis raksts sākas ar API dokumentācijas rakstīšanas ar roku sāpju punktu un pēc tam noved pie Swagger, rīka, kas automātiski ģenerē API dokumentāciju! Pēc tam, izmantojot viegli saprotamu tekstu un attēlus, mēs demonstrēsim, kā izmantot SwaggerUI, lai ģenerētu API dokumentāciju ASP.NET Core WebApi. Visbeidzot, es iepazīstināšu ar dažiem uzlabotiem Swagger lietojumiem ASP.NET Core! Es ceru, ka tas palīdzēs jums izmantot Swagger ASP.NET Core!
|
Publicēts 12.04.2019 14:14:46
|
|
|
|
