(articolo redatto da Gaetano De Pascale)
Le API (Application Programming Interface) sono un elemento fondamentale del mondo della tecnologia moderna. Come documentarle con Swagger te lo racconto in questo articolo.
Che cosa sono le API e perchè documentarle
Le API (Application Programming Interface) sono un elemento fondamentale del mondo della tecnologia moderna. Per definizione, le API sono un insieme di protocolli, strumenti e standard che consentono a diverse applicazioni di comunicare tra loro. Ciò significa che le API sono alla base di molti servizi online e delle applicazioni mobili che utilizziamo tutti i giorni.
Tuttavia, anche se le API sono essenziali per l’interoperabilità delle applicazioni, non sono facili da gestire.
Uno degli aspetti più complessi delle API è la documentazione, che deve essere precisa e completa per garantire che gli sviluppatori possano comprenderne il funzionamento e utilizzarle correttamente.
Ne viene di conseguenza che essa riveste una fase cruciale. Infatti, senza un’adeguata documentazione, anche la migliore delle interfacce potrebbe essere non utilizzata in maniera corretta e comportare problemi non previsti in ambiente di produzione.
Inoltre, come azienda specializzata nel fornire supporto ai clienti, la documentazione delle nostre soluzioni è fondamentale per rendere i nostri servizi il più possibile comprensibili ed autosufficienti verso il mondo esterno.
Tre benefici ottenuti con la documentazione
L’importanza della documentazione può essere riassunta in tre punti principali: la comunicazione, la comprensione e l’efficienza.
Comunicazione
La documentazione delle API serve come mezzo di comunicazione tra gli sviluppatori e gli utenti delle API. Essa descrive le funzionalità e l’uso delle API in un linguaggio comprensibile e facilita la comprensione degli scopi della stessa. Una documentazione chiara e completa permette agli utenti delle API di comprendere facilmente come utilizzarla, senza dover fare affidamento sulla documentazione ufficiale di una libreria o di un framework di terze parti.
Comprensione
La documentazione delle API fornisce informazioni dettagliate sulle funzionalità dell’API, compresi i parametri, le opzioni e gli errori possibili. Inoltre, spesso vengono forniti esempi di codice per illustrare come utilizzare l’API e come interpretare la risposta. Questo tipo di informazioni è fondamentale per la comprensione dell’API e la risoluzione dei problemi.
Efficienza
La documentazione delle API aiuta gli sviluppatori a utilizzare l’API in modo efficiente. Senza una documentazione accurata e completa, gli sviluppatori potrebbero perdere molto tempo nell’individuare come utilizzare correttamente l’API e risolvere eventuali problemi che si presentano durante l’utilizzo. Invece, una documentazione accurata può aiutare gli sviluppatori a risparmiare tempo, migliorare la qualità del codice e sviluppare software più robusti.
Inoltre, last but not least, come spesso accade se diversi gruppi di sviluppo lavorano al Back-End ed al Front-End di un’applicazione, una corretta documentazione dei metodi esposti da un servizio, ad esempio, permette a tutti di lavorare in maniera indipendente senza problemi.
In sintesi, la documentazione delle API è importante perché aiuta gli sviluppatori a comprendere e utilizzare l’API in modo efficiente, migliorando la comunicazione tra gli sviluppatori e riducendo i tempi di sviluppo. Una documentazione accurata e completa può quindi migliorare la qualità del software e la produttività degli sviluppatori.
OpenAPI – Swagger
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
Swagger, che ora è noto come OpenAPI Specification, è un framework open-source per la descrizione, la documentazione e la creazione di API HTTP.
Il suo principale obiettivo è quello di semplificare il processo di documentazione delle API, fornendo uno standard per la descrizione delle API che sia preciso, completo e facilmente comprensibile. Anche se non è l’unico modo per produrre documentazione, si è negli ultimi anni affermato come standard de facto ed il suo utilizzo è sempre più importante soprattutto in gruppi di lavoro decentralizzati.
Come abbiamo visto nel paragrafo precedente, la documentazione delle API è estremamente importante perché consente agli sviluppatori di comprendere rapidamente come funziona un’API e come utilizzarla. Inoltre, una documentazione accurata e dettagliata riduce la curva di apprendimento per gli sviluppatori che utilizzano l’API per la prima volta e aumenta la loro produttività.
In questo senso, è uno strumento estremamente importante. Grazie alla sua capacità di creare documentazione precisa e completa delle API, Swagger semplifica notevolmente il lavoro degli sviluppatori, garantendo che gli utenti dell’API possano comprenderne il funzionamento in modo rapido e completo.
La documentazione prodotta da Swagger è, inoltre, altamente leggibile e facile da interpretare, grazie alla sua struttura chiara e intuitiva. Ciò significa che gli sviluppatori possono capire rapidamente come funziona un’API e come utilizzarla, senza dover passare ore a leggere documenti complessi e poco chiari.
La documentazione Swagger è anche altamente personalizzabile, il che significa che gli sviluppatori possono adattarla alle loro esigenze specifiche. Ad esempio, possono personalizzare la documentazione per soddisfare i requisiti specifici del loro team di sviluppo, includendo informazioni aggiuntive sulle funzionalità dell’API o sulla configurazione.
In aggiunta Swagger offre anche un’interfaccia utente interattiva, nota come Swagger UI, che consente agli sviluppatori di esplorare l’API in modo interattivo. Questa interfaccia utente consente di testare l’API in tempo reale, di esplorare le sue funzionalità e di visualizzare la sua struttura in modo dettagliato. Ciò semplifica notevolmente il processo di sviluppo dell’API, poiché gli sviluppatori possono testare le loro modifiche all’API in tempo reale e vedere immediatamente il loro impatto sulla documentazione.
Avere un back-end conforme alla specifica OpenAPI fornisce un ulteriore vantaggio di non poca importanza. Tale vantaggio è costituito dalla possibilità di generare automaticamente sia i modelli che i servizi necessari per dialogare con gli endpoint esposti dal back-end attraverso strumenti automatici o tool (Es. i pacchetti npm per le nostre applicazioni front-end Angular o React).
In conclusione, se sei coinvolto in un progetto di sviluppo software che utilizza le API, non sottovalutare l’importanza della documentazione delle API. Utilizzare una tecnologia come Swagger per creare documentazione precisa e completa delle API può semplificare notevolmente il lavoro degli sviluppatori e garantire il successo del tuo progetto.
Come utilizzare Swagger con C#
Prima di tutto, è necessario installare il pacchetto NuGet di Swashbuckle per C#. Swashbuckle è un’implementazione di Swagger per .NET e semplifica notevolmente la creazione della documentazione delle API.
Ecco come installare Swashbuckle tramite NuGet:
- Aprire Visual Studio e creare un nuovo progetto C# ASP.NET.
- Fare clic con il tasto destro sul progetto e selezionare “Gestione pacchetti NuGet”.
- Installare i pacchetti
- Swashbuckle
- Swashbuckle.AspNetCore
- Swashbuckle.AspNetCore.Annotations
- Una volta installato Swashbuckle, è possibile utilizzarlo per creare la documentazione delle API.
Aggiungiamo le configurazioni per il corretto utilizzo di swagger:
//.....
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Test API",
Description = "Test API for swagger",
TermsOfService = new Uri("https://testapi.com/terms"),
Contact = new OpenApiContact
{
Name = "Example Contact",
Url = new Uri("https://testapi.com/contact")
},
License = new OpenApiLicense
{
Name = "Example License",
Url = new Uri("https://testapi.com/license")
},
});
options.SchemaFilter<ExampleSchemaFilter>();
options.EnableAnnotations();
});
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint(&quot;/swagger/v1/swagger.json&quot;, &quot;v1&quot;);
options.RoutePrefix = string.Empty;
});
}
//.....
Possiamo inoltre aggiungere uno schema da applicare all’Object che passeremo in input:
using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
public class ExampleSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
if (context.Type == typeof(Object))
{
schema.Example = new OpenApiObject()
{
[&quot;firstName&quot;] = new OpenApiString(&quot;John&quot;),
[&quot;lastName&quot;] = new OpenApiString(&quot;Doe&quot;),
};
}
}
}
Ed ecco un esempio di codice C# per creare una API RESTful e utilizzare Swashbuckle per generare automaticamente la documentazione del nostro servizio:
using Microsoft.AspNetCore.Mvc;
using Newtonsoft.Json.Linq;
using Swashbuckle.AspNetCore.Annotations;
using System.Runtime.InteropServices;
using System.Xml.Linq;
namespace WebApiTest.Controllers
{
[Route(&quot;api/[controller]&quot;)]
[ApiController]
public class TestController : ControllerBase
{
/// <param name=&quot;id&quot;>Here is the description for ID.</param>
[HttpDelete(&quot;{id}&quot;)]
[SwaggerOperation(Summary = &quot;Delete a specific Item&quot;, Description = &quot;Delete a single Item given the Id.&quot;)]
public async Task<IActionResult> Delete(long id)
{
// do stuff
return NoContent();
}
[HttpPost]
[SwaggerOperation(Summary = &quot;Creates an Item&quot;, Description = &quot;Creates an Item from the body of the request.&quot;)]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(Object item)
{
// do stuff
return null;
}
}
}
Di seguito riportiamo alcune schermate esemplificative della documentazione che abbiamo implementato:
Come utilizzare Swagger con Java
Prima di tutto, è necessario aggiungere le dipendenze Swagger al progetto Java (java-version: 17 – Spring Boot: 3.0.5).
Utilizzando Maven, si possono aggiungere le seguenti dipendenze al file pom.xml
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
Ora aggiungiamo
- un DTO:
package com.example.demo.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
public class Item {
@Schema(description = "Item ID", example = "1", required = true)
private long id;
@Schema(description = "Item name", example = "First Item", required = true)
@NotBlank
@Size(min = 0, max = 20)
private String name;
@Schema(description = "Item description", example = "First Item description", required = false)
@Size(min = 0, max = 30)
private String description;
// constructor, getter and setter
}
- un controller:
package com.example.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.example.demo.dto.Item;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
@RestController
@RequestMapping("/api/items")
public class ItemController {
@Operation(description = "Get an item by id", summary = "Returns the item having the id in input")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully retrieved"),
@ApiResponse(responseCode = "404", description = "Not found - The item was not found")
})
@GetMapping("/{id}")
public Item findById(
@PathVariable("id") @Parameter(name = "id", description = "Item id", example = "1") long id) {
// code
return new Item();
}
@Operation(description = "Update an item by id", summary = "Update the item with the given id")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully retrieved"),
@ApiResponse(responseCode = "404", description = "Not found - The item was not found")
})
@PutMapping("/{id}")
public Item update(
@PathVariable("id") @Parameter(name = "id", description = "Item id", example = "1") long id,
@RequestBody final Item item) {
// code
return item;
}
}
- Possiamo lanciare l’applicazione e verificare che la nostra documentazione si presente su swagger
Conclusioni
Sei pronto a usare Swagger per documentare le tue API? Facci sapere che cosa ne pensi e continua a seguire il nostro blog.
Se anche tu vuoi occuparti di progetti di ricerca e sviluppo IT di ultima generazione
dai un’occhiata alle nostre opportunità di lavoro e conosciamoci subito!
