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

Par Christoph Nienaber et Rico SuterBy Christoph Nienaber and Rico Suter

Swagger (OpenAPI) est une spécification indépendante du langage pour décrire les API REST.Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. Cela permet aux ordinateurs et aux êtres humains de comprendre les fonctionnalités d’une API REST sans accès direct au code source.It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Ses principaux objectifs sont les suivants :Its main goals are to:

  • Réduisez la quantité de travail nécessaire pour connecter les services découplés.Minimize the amount of work needed to connect decoupled services.
  • Réduire la durée nécessaire pour documenter un service avec précision.Reduce the amount of time needed to accurately document a service.

Les deux principales implémentations OpenAPI pour .NET sont Swashbuckle et NSwag, consultez :The two main OpenAPI implementations for .NET are Swashbuckle and NSwag, see:

OpenApi et SwaggerOpenApi vs. Swagger

Le projet Swagger a été reporté à l’initiative OpenAPI dans 2015 et a été désigné comme OpenAPI.The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. Les deux noms sont utilisés de façon interchangeable.Both names are used interchangeably. Toutefois, « OpenAPI » fait référence à la spécification.However, "OpenAPI" refers to the specification. « Swagger » fait référence à la famille de produits open source et commerciales de l’API smartbear qui fonctionnent avec la spécification OpenAPI."Swagger" refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. 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.Subsequent open-source products, such as OpenAPIGenerator, also fall under the Swagger family name, despite not being released by SmartBear.

En résumé :In short:

  • OpenAPI est une spécification.OpenAPI is a specification.
  • Swagger est un outil qui utilise la spécification OpenAPI.Swagger is tooling that uses the OpenAPI specification. Par exemple, OpenAPIGenerator et SwaggerUI.For example, OpenAPIGenerator and SwaggerUI.

Spécification OpenAPI (openapi.js)OpenAPI specification (openapi.json)

La spécification OpenAPI est un document qui décrit les fonctionnalités de votre API.The OpenAPI specification is a document that describes the capabilities of your API. Le document est basé sur les annotations XML et d’attribut dans les contrôleurs et les modèles.The document is based on the XML and attribute annotations within the controllers and models. Il s’agit de la partie fondamentale du Flow OpenAPI et est utilisée pour diriger les outils tels que SwaggerUI.It's the core part of the OpenAPI flow and is used to drive tooling such as SwaggerUI. Par défaut, il est nommé openapi.js.By default, it's named openapi.json. Voici un exemple de spécification OpenAPI, réduite par souci de concision :Here's an example of an OpenAPI specification, reduced for brevity:

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

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.Swagger UI offers a web-based UI that provides information about the service, using the generated OpenAPI specification. 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).Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. L’IU web ressemble à ceci :The web UI looks like this:

Interface utilisateur Swagger

Chaque méthode d’action publique dans vos contrôleurs peut être testée à partir de l’IU.Each public action method in your controllers can be tested from the UI. Sélectionnez un nom de méthode pour développer la section.Select a method name to expand the section. Ajoutez tous les paramètres nécessaires, puis sélectionnez essayer !.Add any necessary parameters, and select Try it out!.

Exemple de test GET Swagger

Notes

La version de l’IU Swagger utilisée pour les captures d’écran est la version 2.The Swagger UI version used for the screenshots is version 2. Pour obtenir un exemple de la version 3, consultez l’exemple Petstore.For a version 3 example, see Petstore example.

Étapes suivantesNext steps