Questo post è stato modificato l'ultima volta da QWERTYU il 12-04-2019 alle 14:24
IntroduzioneDopo aver utilizzato asp.net Core per lo sviluppo di API, scrivere documentazione API deve essere un compito doloroso per i programmatori, ma la documentazione deve essere scritta e, se non ci sono requisiti specifici per il formato della documentazione, la documentazione finale dipende interamente dall'umore dello sviluppatore. O essere più dettagliato, o più semplice. Quindi esiste un modo rapido ed efficiente per costruire la documentazione delle API? La risposta è sì, Swagger è uno degli strumenti di generazione di documentazione per API REST più popolari!
Perché usare Swagger come strumento di generazione di documentazione per le API REST- Swagger può generare una console API interattiva che gli sviluppatori possono utilizzare per imparare e sperimentare rapidamente con le API.
- Swagger può generare codice client SDK per implementazioni su diverse piattaforme.
- I file Swagger possono essere generati automaticamente dai commenti del codice su molte piattaforme diverse.
- Swagger ha una comunità forte con molti contributori forti.
Come utilizzare Swagger per generare documentazione API nel asp.net core?- Swashbuckle.AspNetCore è un progetto open-source che genera documentazione Swagger per ASP.NET Core Web API.
- NSwag è un altro progetto open-source per integrare Swagger UI o ReDoc nelle ASP.NET API Web Core. Fornisce un modo per generare codice client C# e TypeScript per le API.
Di seguito è un esempio di Swashbuckle.AspNetCoreQuali sono i componenti di un Swashbuckle?- Swashbuckle.AspNetCore.Swagger: Espone l'oggetto SwaggerDocument come modello oggetto Swagger e middleware per endpoint JSON.
- Swashbuckle.AspNetCore.SwaggerGen: Un generatore Swagger che genera oggetti SwaggerDocument direttamente da route, controller e modelli. Spesso viene combinato con il middleware Swagger endpoint per esporre automaticamente il JSON Swagger.
- Swashbuckle.AspNetCore.SwaggerUI: Una versione incorporata dello strumento Swagger UI. Interpreta Swagger JSON per costruire esperienze personalizzabili e ricche che descrivono la funzionalità delle Web API. Include strumenti di test integrati per i metodi comuni.
Come installare Swashbuckle con vs2017?
Il primo modo: installa dalla finestra della Console del Package Manager
- Vai su Visualizzazioni > altre console del gestore pacchetti di Windows >
- Naviga fino alla directory che contiene il file TodoApi.csproj
- Si prega di eseguire il seguente comando · Install-Package Swashbuckle.AspNetCore
-
Secondo modo: dalla finestra di dialogo Gestisci i pacchetti NuGet:- Clicca con il tasto destro sul progetto in Esplora soluzioni > Gestisci i pacchetti NuGet
- Imposta il codice sorgente del pacchetto su nuget.org
- Digita "Swashbuckle.AspNetCore" nella casella di ricerca
- Seleziona il pacchetto Swashbuckle.AspNetCore nella scheda Sfoglia e clicca su Installa
-
Aggiungi e configura il middleware SwaggerIntrodurre prima il namespace: Aggiungi il generatore Swagger alla collezione di servizi nel metodo Startup.ConfigureServices: aAvvio.Configurazionemetodo, abilitare il middleware di servire il documento JSON generato e l'interfaccia utente Swagger:
Avvia l'app e accedihttps://localhost:<port>/swagger/v1/swagger.json。 La documentazione risultante che descrive l'endpoint è visualizzata in formato JSON come segue.
Disponibilehttps://localhost:<port>/swaggerTrova l'interfaccia di Swagger. Consulta la documentazione API tramite l'interfaccia di Swagger come mostrato di seguito.
Per applicare la radice (http://localhost:<port>/) per fornire l'interfaccia di Swagger, per favore inserisci ilPrefisso Route.La proprietà è impostata su una stringa vuota:
Uso avanzato di Swagger (personalizzazione ed estensioni)Usa Swagger per aggiungere informazioni esplicative alla documentazione APILe seguenti operazioni di configurazione vengono eseguite nel metodo AddSwaggerGen, che aggiunge informazioni come autore, licenza e descrizione: Le informazioni sulla versione di visualizzazione dell'interfaccia utente di wagger sono mostrate nella figura seguente: Aggiungi commenti ai metodi di interfacciaClicchiamo prima sull'API, espandiamo come mostrato nella figura qui sotto, non ci possono essere commenti, come aggiungerli? Aggiungi commenti ai documenti con tre/come mostrato nell'immagine sottostante, come mostrato qui sotto Poi esegui il progetto e torna su swaggerUI per vedere se il commento appare Non è ancora apparso, non preoccuparti, guarda giù! Abilita le annotazioni XMLPuoi abilitare le annotazioni XML usando i seguenti metodi: - Clicca con il tasto destro sul progetto in Esplora soluzioni e seleziona Proprietà
- Guarda la casella File del Documento XML sotto la sezione Output della scheda Build
-
Abilitare le annotazioni XML fornisce informazioni di debug per tipi e membri comuni non documentati. Se compaiono molti messaggi di avvertimento, ad esempio, il seguente messaggio indica una violazione del codice di avviso 1591:
E se hai il disturbo ossessivo-compulsivo e vuoi annullare l'avvertimento? Puoi annullare come mostrato nell'immagine qui sotto
Si noti il percorso del file del documento xml generato sopra,
Nota: 1. Per sistemi operativi Linux o non Windows, i nomi e i percorsi dei file sono distinti dalla mazzedra. Ad esempio, un file "SwaggerDemo.xml" funziona su Windows, ma non su CentOS. 2. Per ottenere il percorso applicativo, si consiglia di utilizzare AppContext.BaseDirectory per ottenerlo Ricostruisci e gestisce il progetto per vedere se compaiono i commenti Dall'operazione sopra, si può riassumere che l'interfaccia di Swagger mostra il <summary> testo interno degli elementi del codice commento sopra come commenti API di grande dimensione! Naturalmente, puoi anche aggiungere l'elemento osservazioni alla documentazione di come fare. Può integrare <summary> le informazioni specificate nell'elemento e fornire un'interfaccia Swagger più affidabile. <remarks> Il contenuto degli elementi può contenere testo, JSON o XML. Il codice è il seguente: Testa l'interfaccia API usando SwaggerUIFacciamo il debug dell'interfaccia tramite SwaggerUI con un piccolo esempio
- Clicca su un'interfaccia API che deve essere testata, poi clicca sul pulsante "Prova" a sinistra e a destra di Parametri
- Inserisci un parametro nella finestra di testo del parametro che appare, come mostrato nell'immagine seguente, inserisci il parametro 2
- Clicca sul pulsante Esegui e apparirà la Risposta formattata mostrata qui sotto, come mostrato nella figura qui sotto
Bene, questo è tutto per il tutorial di oggi sull'uso di Swagger per generare documentazione API in ASP.NET Core WebApi. Spero che ti sarà utile imparare a usare Swagger per generare documentazione API in ASP.NET Core! sommarioQuesto articolo parte dal punto critico della scrittura manuale della documentazione API, per poi arrivare a Swagger, uno strumento che genera automaticamente documentazione API! Poi, attraverso testo e immagini facili da comprendere, dimostreremo come utilizzare SwaggerUI per generare documentazione API in una ASP.NET Core WebApi. Infine, introdurrò alcuni usi avanzati di Swagger in ASP.NET Core! Spero ti aiuti a usare Swagger in ASP.NET Core!
| 
Pubblicato su 12/04/2019 14:14:46
|
|
|
|
