Documentazione delle API Web ASP.NET Core con Swagger/OpenAPI

  • 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:

Interfaccia utente di Swagger

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.

Esempio test GET di Swagger

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:

Interfaccia utente di Swagger

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.

Esempio test GET di Swagger

Nota

La versione di Swagger UI usata per le schermate è la versione 2. Per un esempio con la versione 3, vedere l'esempio Petstore.

Passaggi successivi