Documentation de l’API web ASP.NET Core avec Swagger/OpenAPI

Par Christoph Nienaber et Rico Suter

Swagger (OpenAPI) est une spécification indépendante du langage pour décrire REST les API. Il permet aux ordinateurs et aux humains de comprendre les fonctionnalités d’une REST API sans accès direct au code source. Ses principaux objectifs sont les suivants :

  • Réduisez la quantité de travail nécessaire pour connecter les services découplés.
  • Réduisez le temps nécessaire pour documenter avec précision un service.

Les deux principales implémentations OpenAPI pour .NET sont Swashbuckle et NSwag. Consultez :

OpenAPI et Swagger

Le projet Swagger a été donné à l’initiative OpenAPI en 2015 et a depuis été appelé OpenAPI. Les deux noms sont utilisés indifféremment. Toutefois, « OpenAPI » fait référence à la spécification. « Swagger » fait référence à la famille de produits open source et commerciaux de SmartBear qui fonctionnent avec la spécification OpenAPI. Les produits open source suivants, tels que OpenAPIGenerator, sont également sous le nom de famille Swagger, bien qu’ils ne soient pas publiés par SmartBear.

En résumé :

  • OpenAPI est une spécification.
  • Swagger est un outil qui utilise la spécification OpenAPI. Par exemple, OpenAPIGenerator et SwaggerUI.

Spécification OpenAPI (openapi.json)

La spécification OpenAPI est un document qui décrit les fonctionnalités de votre API. Le document est basé sur les annotations XML et d’attribut dans les contrôleurs et les modèles. Il s’agit de la partie principale du flux OpenAPI et est utilisé pour piloter des outils tels que SwaggerUI. Par défaut, il est nommé openapi.json. Voici un exemple de spécification OpenAPI, réduite par souci de concision :

{
  "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

Swagger UI offre une interface utilisateur web qui fournit des informations sur le service, à l’aide de la spécification OpenAPI générée. Swashbuckle et NSwag ont une version incorporée à l’interface utilisateur Swagger pour que vous puissiez l’héberger dans votre application ASP.NET Core à l’aide d’un appel d’inscription d’intergiciel (middleware). L’IU web ressemble à ceci :

Interface utilisateur Swagger

Chaque méthode d’action publique dans vos contrôleurs peut être testée à partir de l’IU. Sélectionnez un nom de méthode pour développer la section. Ajoutez les paramètres nécessaires, puis sélectionnez Essayer!.

Exemple de test GET Swagger

Notes

La version de l’IU Swagger utilisée pour les captures d’écran est la version 2. Pour obtenir un exemple de la version 3, consultez l’exemple Petstore.

Étapes suivantes