Această postare a fost editată ultima dată de QWERTYU pe 2019-4-12, 14:24
IntroducereDupă folosirea asp.net Core pentru dezvoltarea API-urilor, scrierea documentației API trebuie să fie o sarcină dureroasă pentru programatori, dar documentația trebuie scrisă, iar dacă nu există cerințe specifice pentru formatul documentației, documentația finală depinde în totalitate de starea de spirit a dezvoltatorului. Sau să fie mai detaliate sau mai simple. Există o metodă rapidă și eficientă de a construi documentația API-ului? Răspunsul este da, Swagger este unul dintre cele mai populare instrumente de generare a documentației API-urilor REST!
De ce să folosești Swagger ca instrument de generare a documentației API-urilor REST- Swagger poate genera o consolă API interactivă pe care dezvoltatorii o pot folosi pentru a învăța rapid și a experimenta cu API-uri.
- Swagger poate genera cod SDK client pentru implementări pe o varietate de platforme diferite.
- Fișierele Swagger pot fi generate automat din comentarii de cod pe multe platforme diferite.
- Swagger are o comunitate puternică, cu mulți contributori puternici.
Cum să folosești Swagger pentru a genera documentație API în nucleul asp.net?- Swashbuckle.AspNetCore este un proiect open-source care generează documentația Swagger pentru ASP.NET API Web Core.
- NSwag este un alt proiect open-source pentru integrarea Swagger UI sau ReDoc în API-urile web ASP.NET Core. Oferă o modalitate de a genera cod client C# și TypeScript pentru API-uri.
Următorul este un exemplu de Swashbuckle.AspNetCoreCare sunt componentele unui Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Expune obiectul SwaggerDocument ca model de obiect Swagger și middleware pentru endpoint-uri JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Un generator Swagger care generează obiecte SwaggerDocument direct din rute, controlere și modele. Este adesea combinat cu middleware-ul Swagger pentru a expune automat JSON-ul Swagger.
- Swashbuckle.AspNetCore.SwaggerUI: O versiune încorporată a instrumentului Swagger UI. Interpretează Swagger JSON pentru a construi experiențe personalizabile și bogate care descriu funcționalitatea API-urilor web. Include instrumente de testare integrate pentru metodele comune.
Cum să instalezi Swashbuckle cu vs2017?
Prima metodă: instalează din fereastra Package Manager Console
- Mergi la Vizualizări > alte console Windows > Package Manager
- Navighează la directorul care conține fișierul TodoApi.csproj
- Vă rugăm să executați următoarea comandă · Install-Package Swashbuckle.AspNetCore
-
A doua variantă: Din dialogul Gestionează pachetele NuGet:- Faceți clic dreapta pe proiect în Solution Explorer > Gestionați pachetele NuGet
- Setează sursa pachetului pe nuget.org
- Tastează "Swashbuckle.AspNetCore" în caseta de căutare
- Selectează pachetul Swashbuckle.AspNetCore din fila Browse și apasă pe Install
-
Adaugă și configurează middleware-ul SwaggerIntroduceți mai întâi spațiul de nume: Adaugă generatorul Swagger la colecția de servicii în metoda Startup.ConfigureServices: laStart.Configuremetodă, permite middleware-ul să servească documentul JSON generat și interfața Swagger:
Lansează aplicația și navighează către eahttps://localhost:<port>/swagger/v1/swagger.json。 Documentația rezultată care descrie punctul final este afișată în format JSON după cum urmează.
Disponibilhttps://localhost:<port>/atitudineGăsește interfața Swagger. Răsfoiește documentația API prin interfața Swagger, așa cum este prezentat mai jos.
Pentru a aplica rădăcina (http://localhost:<port>/) pentru a oferi interfața Swagger, vă rugăm să punețiRoutePrefixProprietatea este setată la un șir gol:
Utilizare avansată a Swaggerului (personalizare și extensii)Folosește Swagger pentru a adăuga informații explicative în documentația API-uluiUrmătoarele operații de configurare sunt efectuate în metoda AddSwaggerGen, care adaugă informații precum autorul, licența și descrierea: Informațiile despre versiunea de afișare a interfeței wagger sunt prezentate în următoarea figură: Adaugă comentarii la metodele de interfațăHai să dăm click pe API mai întâi, să extindem așa cum se vede în figura de mai jos, nu pot exista comentarii, cum se adaugă comentarii? Adaugă comentarii la document cu trei ca prezentate în imaginea de mai jos, așa cum este prezentat mai jos Apoi rulează proiectul și revino la swaggerUI să vezi dacă apare comentariul Tot nu a apărut, nu-ți face griji, uită-te în jos! Activează adnotările XMLPoți activa adnotările XML folosind următoarele metode: - Faceți clic dreapta pe proiect în Solution Explorer și selectați Proprietăți
- Uită-te la caseta XML Document File din secțiunea Output din fila Build
-
Activarea adnotărilor XML oferă informații de depanare pentru tipuri și membri comuni nedocumentați. Dacă apar multe mesaje de avertizare, de exemplu, următorul mesaj indică o încălcare a codului de avertizare 1591:
Ce se întâmplă dacă ai OCD și vrei să anulezi avertismentul? Poți anula așa cum se vede în imaginea de mai jos
Observați calea fișierului documentului xml generat mai sus,
Notă: 1. Pentru sistemele de operare Linux sau non-Windows, numele și căile fișierelor sunt sensibile la majuscule. De exemplu, un fișier "SwaggerDemo.xml" funcționează pe Windows, dar nu și pe CentOS. 2. Pentru a obține calea aplicației, se recomandă utilizarea AppContext.BaseDirectory pentru a o obține Reconstruiește și rulează proiectul ca să vezi dacă apar comentariile Din operația de mai sus, se poate rezuma că interfața Swagger afișează <summary> textul intern al elementelor codului comentariului de mai sus ca comentarii API mari! Desigur, poți adăuga și elementul de remarci în documentația Obține instrucțiuni. Poate completa <summary> informațiile specificate în element și poate oferi o interfață Swagger mai fiabilă. <remarks> Conținutul elementelor poate conține text, JSON sau XML. Codul este următorul: Testează interfața API folosind SwaggerUISă depanăm interfața prin SwaggerUI printr-un mic exemplu
- Apasă pe o interfață API care trebuie testată, apoi apasă butonul "Testează-l" din stânga și dreapta din Parameters
- Introduceți un parametru în căsuța de text a parametrilor care apare, așa cum se arată în imaginea următoare, introduceți parametrul 2
- Apasă butonul Execută, iar răspunsul formatat prezentat mai jos va apărea, așa cum se vede în figura de mai jos
Ei bine, asta e tot pentru tutorialul de astăzi despre cum să folosești Swagger pentru a genera documentație API în ASP.NET Core WebApi. Sper că îți va fi de ajutor să înveți cum să folosești Swagger pentru a genera documentație API în ASP.NET Core! rezumatAcest articol începe cu punctul sensibil al scrierii manuale a documentației API, apoi duce la Swagger, un instrument care generează automat documentația API! Apoi, prin text și imagini ușor de înțeles, vom demonstra cum să folosim SwaggerUI pentru a genera documentație API într-un ASP.NET Core WebApi. În final, voi introduce câteva utilizări avansate ale lui Swagger în ASP.NET Core! Sper să te ajute să folosești Swagger în ASP.NET Core!
| 
Postat pe 12.04.2019 14:14:46
|
|
|
|
