Introduzione
Documentare il software che si compila offre molti vantaggi. Non solo una documentazione valida fa sì che il codice venga gestito con maggior semplicità nel corso del tempo, lo rende anche più utilizzabile da parte di altri utenti. Rendere il codice più utilizzabile è particolarmente importante quando si compila un'API che verrà usata da altri. Per fortuna, sono disponibili strumenti e framework che consentono di ridurre il costo della produzione di documentazione di buon livello.
Si supponga di essere lo sviluppatore responsabile in un'azienda di cornici per stampa. La società decide di rendere pubbliche le proprie API. Per molte delle API non vi è alcuna documentazione esistente ed è lo sviluppatore a doverla creare. Se le API sono documentate, è più facile per i partner aziendali usarle correttamente, con conseguente riduzione dei costi per assistenza e gestione.
È necessario un modo semplice e standardizzato per documentare ogni API. È anche necessario un metodo per ospitare la documentazione in una posizione accessibile per i partner.
In questo modulo verrà illustrato come documentare un'API ASP.NET Core esistente con Swashbuckle, Swagger, Swagger UI e OpenAPI.
Obiettivi di apprendimento
Contenuto del modulo:
- Informazioni su Swashbuckle, OpenAPI e Swagger UI.
- Abilitare OpenAPI per un'API in C#/ASP.NET Core.
- Usare Swashbuckle in un'API in C#/ASP.NET Core.
- Generare e visualizzare la documentazione dell'API con OpenAPI.
Prerequisiti
- Esperienza di progettazione e implementazione di API REST.
- Esperienza di sviluppo di app ASP.NET Core di base.
- Installazioni locali di .NET SDK, Visual Studio Code e dell'estensione C# per Visual Studio Code.