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

Par Christoph Nienaber et Rico Suter

Swagger (OpenAPI) est une spécification indépendante du langage pour décrire les API REST. Cela permet aux ordinateurs et aux êtres humains de comprendre les fonctionnalités d’une API REST 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éduire la durée nécessaire pour documenter un service avec précision.

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

OpenApi et Swagger

Le projet Swagger a été reporté à l’initiative OpenAPI dans 2015 et a été désigné comme OpenAPI. Les deux noms sont utilisés de façon interchangeable. Toutefois, « OpenAPI » fait référence à la spécification. « Swagger » fait référence à la famille de produits open source et commerciales de l’API 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 l’API 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.js)

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 fondamentale du Flow OpenAPI et est utilisée pour diriger les outils tels que SwaggerUI. Par défaut, il est nommé openapi.js. 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

L' interface utilisateur de Swagger offre une interface utilisateur basée sur le 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 tous 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