In uno script precedente (https://www.aspitalia.com/script/1301/Documentare-Web-API-Swagger-ASP.NET-Core-2.1.aspx), abbiamo visto come configurare Swashbuckle.AspNetCore per generare automaticamente lo swagger document della nostra API.

Quando dobbiamo supportare diverse versioni del client contemporaneamente, la tipica soluzione è quella di esporre la versione dell'API come path dell'URL: /api/v2/people.

Dato che queste API avranno verosimilmente contratti differenti, è possibile esporre diversi swagger document tramite il metodo AddSwaggerGen:

public void ConfigureServices(IServiceCollection services)
{
    // .. altro codice qui ..

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My Sample API V1", Version = "v1" });
        c.SwaggerDoc("v2", new Info { Title = "My Sample API V2", Version = "v2" });
    });
}

Ognuno di questi document risponderà a uno specifico indirizzo, che possiamo registrare nella UI per generare una pagina di help per ciascuno di essi:

app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
  c.SwaggerEndpoint("/swagger/v2/swagger.json", "My API V2");
});

Swashbuckle utilizza le primitive di ApiExplorer per ispezionare il nostro codice alla ricerca di controller e action. Per specificare la versione di ciascun endpoint disponibile, è pertanto sufficiente sfruttare l'attributo ApiExplorerSettings, che può essere applicato sia a livello di controller che di action.

[Route("api/v2/people")]
[ApiExplorerSettings(GroupName = "v2")]
public class PeopleV2Controller : Controller
{
    // .. altro codice qui ..
}