Par Christoph Nienaber et Rico Suter
Swagger (OpenAPI) est une spécification indépendante du langage qui permet de décrire les API REST. Non seulement elle facilite la compréhension des fonctionnalités d’une API par les ordinateurs, mais elle permet également aux humains d’accéder à cette information sans avoir accès direct au code source. Les objectifs principaux de Swagger sont les suivants :
- Réduire la quantité de travail nécessaire pour connecter des services découplés.
- Réduire le temps nécessaire pour documenter avec précision un service.
Si vous travaillez avec .NET, vous avez deux principales implémentations OpenAPI à votre disposition : Swashbuckle et NSwag. Vous pouvez consulter les ressources suivantes pour démarrer avec ces outils :
OpenAPI et Swagger
Le projet Swagger a été donné à l’initiative OpenAPI en 2015 et depuis lors, il est également appelé OpenAPI. Les deux termes sont utilisés de manière interchangeable, mais il y a une nuance importante. “OpenAPI” fait référence à la spécification elle-même, tandis que “Swagger” fait référence à la famille de produits open source et commerciaux de SmartBear qui fonctionnent avec la spécification OpenAPI. Il existe également d’autres produits open source, tels que OpenAPIGenerator, qui font partie de la famille Swagger, bien qu’ils ne soient pas publiés par SmartBear.
En résumé :
- OpenAPI est une spécification.
- Swagger est un ensemble d’outils qui utilisent la spécification OpenAPI, tels que OpenAPIGenerator et SwaggerUI.
Spécification OpenAPI (openapi.json)
La spécification OpenAPI est un document qui décrit les fonctionnalités de votre API. Ce document est basé sur les annotations XML et les attributs dans vos contrôleurs et modèles. Il s’agit de la partie centrale du flux OpenAPI et est utilisé pour alimenter des outils tels que SwaggerUI. Par défaut, ce document est généralement nommé openapi.json. Voici un exemple réduit de spécification OpenAPI :
{
"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
}
}
}
}Interface utilisateur Swagger
L’interface utilisateur Swagger est une interface web qui fournit des informations sur votre service à l’aide de la spécification OpenAPI générée. Swashbuckle et NSwag incluent une version de l’interface utilisateur Swagger intégrée, que vous pouvez héberger dans votre application ASP.NET Core en utilisant un middleware. L’interface web Swagger ressemble à ceci :
Chaque méthode d’action publique dans vos contrôleurs peut être testée directement depuis l’interface utilisateur. Il suffit de cliquer sur le nom d’une méthode pour développer la section correspondante. Vous pouvez ensuite ajouter tous les paramètres nécessaires et cliquer sur “L’essayer!” pour tester la méthode.
Sécurisation des points de terminaison de l’interface utilisateur Swagger
Si vous souhaitez sécuriser les points de terminaison de l’interface utilisateur Swagger, vous pouvez utiliser la méthode MapSwagger().RequireAuthorization(). Voici un exemple :
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();
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);
}Dans l’exemple ci-dessus, le point de terminaison /weatherforecast ne nécessite pas d’autorisation, contrairement aux points de terminaison de l’interface utilisateur Swagger.
Pour tester les points de terminaison de l’interface utilisateur Swagger, vous pouvez utiliser la commande Curl suivante en remplaçant {token} par votre propre jeton JWT :
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.jsonPour obtenir plus d’informations sur le test avec des jetons JWT, consultez la documentation sur la génération de jetons avec dotnet user-jwts.
Étapes suivantes
Si vous souhaitez en savoir plus sur Swagger et comment l’utiliser dans votre projet, vous pouvez consulter les ressources suivantes :
