Documentazione delle API Web ASP.NET Core con Swagger/OpenAPI
Nota
Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.
Avviso
Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.
Importante
Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.
Per la versione corrente, vedere la versione .NET 8 di questo articolo.
Di Christoph Nienaber e Rico Suter
Swagger (OpenAPI) è una specifica indipendente dal linguaggio per la descrizione delle REST API. Consente sia ai computer che agli esseri umani di comprendere le funzionalità di un'API REST senza accesso diretto al codice sorgente. I suoi obiettivi principali sono:
- Ridurre al minimo la quantità di lavoro necessaria per connettere i servizi disaccoppiati.
- Ridurre la quantità di tempo necessaria per documentare in modo accurato un servizio.
Le due implementazioni Principali di OpenAPI per .NET sono Swashbuckle e NSwag, vedere:
OpenAPI e Swagger
Il progetto Swagger è stato donato all'iniziativa OpenAPI nel 2015 e da allora è stato definito OpenAPI. Entrambi i nomi vengono usati in modo intercambiabile. Tuttavia, "OpenAPI" fa riferimento alla specifica. "Swagger" si riferisce alla famiglia di prodotti open source e commerciali di SmartBear che funzionano con la specifica OpenAPI. I prodotti open source successivi, ad esempio OpenAPIGenerator, rientrano anche nel nome della famiglia Swagger, nonostante non vengano rilasciati da SmartBear.
In breve:
- OpenAPI è una specifica.
- Swagger è uno strumento che usa la specifica OpenAPI. Ad esempio, OpenAPIGenerator e SwaggerUI.
Specifica OpenAPI (openapi.json
)
La specifica OpenAPI è un documento che descrive le funzionalità dell'API. Il documento si basa sulle annotazioni XML e attributi all'interno dei controller e dei modelli. È la parte principale del flusso OpenAPI e viene usata per guidare strumenti come SwaggerUI. Per impostazione predefinita, è denominato openapi.json
. Di seguito è riportato un esempio di specifica OpenAPI, ridotta per brevità:
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Interfaccia utente di Swagger
L'interfaccia utente di Swagger offre un'interfaccia utente basata sul Web che fornisce informazioni sul servizio, usando la specifica OpenAPI generata. Sia Swashbuckle sia NSwag includono una versione incorporata di Swagger UI che può essere ospitata nell'applicazione ASP.NET Core dell'utente con una chiamata di registrazione middleware. L'interfaccia utente Web è simile alla seguente:
Ogni metodo di azione pubblico nei controller può essere testato dall'interfaccia utente. Selezionare un nome di metodo per espandere la sezione. Aggiungere i parametri necessari e selezionare Prova.
Nota
La versione di Swagger UI usata per le schermate è la versione 2. Per un esempio con la versione 3, vedere l'esempio Petstore.
Protezione degli endpoint dell'interfaccia utente di Swagger
Chiamare MapSwagger().RequireAuthorization
per proteggere gli endpoint dell'interfaccia utente di Swagger. L'esempio seguente protegge gli endpoint swagger:
using System.Security.Claims;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
var summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
app.MapSwagger().RequireAuthorization();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
.RequireAuthorization();
app.MapGet("/weatherforecast", () =>
{
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
(
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
))
.ToArray();
return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi();
app.Run();
internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
Nel codice precedente l'endpoint non richiede l'autorizzazione /weatherforecast
, ma gli endpoint Swagger lo fanno.
Il curl seguente passa un token JWT per testare l'endpoint dell'interfaccia utente di Swagger:
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json
Per altre informazioni sui test con token JWT, vedere Generare token con dotnet user-jwts.
Generare un file di documentazione XML in fase di compilazione.
Per altre informazioni, vedere GenerateDocumentationFile .
Passaggi successivi
Di Christoph Nienaber e Rico Suter
Swagger (OpenAPI) è una specifica indipendente dal linguaggio per la descrizione delle REST API. Consente sia ai computer che agli esseri umani di comprendere le funzionalità di un'API REST senza accesso diretto al codice sorgente. I suoi obiettivi principali sono:
- Ridurre al minimo la quantità di lavoro necessaria per connettere i servizi disaccoppiati.
- Ridurre la quantità di tempo necessaria per documentare in modo accurato un servizio.
Le due implementazioni Principali di OpenAPI per .NET sono Swashbuckle e NSwag, vedere:
OpenAPI e Swagger
Il progetto Swagger è stato donato all'iniziativa OpenAPI nel 2015 e da allora è stato definito OpenAPI. Entrambi i nomi vengono usati in modo intercambiabile. Tuttavia, "OpenAPI" fa riferimento alla specifica. "Swagger" si riferisce alla famiglia di prodotti open source e commerciali di SmartBear che funzionano con la specifica OpenAPI. I prodotti open source successivi, ad esempio OpenAPIGenerator, rientrano anche nel nome della famiglia Swagger, nonostante non vengano rilasciati da SmartBear.
In breve:
- OpenAPI è una specifica.
- Swagger è uno strumento che usa la specifica OpenAPI. Ad esempio, OpenAPIGenerator e SwaggerUI.
Specifica OpenAPI (openapi.json
)
La specifica OpenAPI è un documento che descrive le funzionalità dell'API. Il documento si basa sulle annotazioni XML e attributi all'interno dei controller e dei modelli. È la parte principale del flusso OpenAPI e viene usata per guidare strumenti come SwaggerUI. Per impostazione predefinita, è denominato openapi.json
. Di seguito è riportato un esempio di specifica OpenAPI, ridotta per brevità:
{
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
},
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
],
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
}
}
}
}
}
}
},
"post": {
…
}
},
"/api/Todo/{id}": {
"get": {
…
},
"put": {
…
},
"delete": {
…
}
}
},
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"isCompleted": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
Interfaccia utente di Swagger
L'interfaccia utente di Swagger offre un'interfaccia utente basata sul Web che fornisce informazioni sul servizio, usando la specifica OpenAPI generata. Sia Swashbuckle sia NSwag includono una versione incorporata di Swagger UI che può essere ospitata nell'applicazione ASP.NET Core dell'utente con una chiamata di registrazione middleware. L'interfaccia utente Web è simile alla seguente:
Ogni metodo di azione pubblico nei controller può essere testato dall'interfaccia utente. Selezionare un nome di metodo per espandere la sezione. Aggiungere i parametri necessari e selezionare Prova.
Nota
La versione di Swagger UI usata per le schermate è la versione 2. Per un esempio con la versione 3, vedere l'esempio Petstore.