Pages d’aide d’API web ASP.NET Core avec Swagger/OpenAPIASP.NET Core web API help pages with Swagger / OpenAPI

Par Christoph Nienaber et Rico SuterBy Christoph Nienaber and Rico Suter

Lorsque vous consommez une API Web, la compréhension de ses différentes méthodes peut être difficile pour un développeur.When consuming a web API, understanding its various methods can be challenging for a developer. Swagger, également connu sous le nom de openapi, résout le problème de génération de la documentation et des pages d’aide utiles pour les API Web.Swagger, also known as OpenAPI, solves the problem of generating useful documentation and help pages for web APIs. Ses avantages sont, entre autres, la documentation interactive, la génération de SDK client et la découvertibilité des API.It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

Cet article décrit les implémentations .NET Swagger suivantes Swashbuckle.AspNetCore et NSwag :In this article, the Swashbuckle.AspNetCore and NSwag .NET Swagger implementations are showcased:

  • Swashbuckle.AspNetCore est un projet open source pour la génération de documents Swagger pour des API web ASP.NET Core.Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs.

  • NSwag est un autre projet open source pour générer des documents Swagger et intégrer l’IU Swagger ou ReDoc aux API web ASP.NET Core.NSwag is another open source project for generating Swagger documents and integrating Swagger UI or ReDoc into ASP.NET Core web APIs. NSwag fournit aussi des méthodes pour générer du code client C# et TypeScript pour votre API.Additionally, NSwag offers approaches to generate C# and TypeScript client code for your API.

Qu’est-ce que Swagger/OpenAPI ?What is Swagger / OpenAPI?

Swagger est une spécification indépendante du langage pour décrire les API REST.Swagger is a language-agnostic specification for describing REST APIs. Le projet Swagger a été donné au projet OpenAPI Initiative et s’appelle maintenant OpenAPI.The Swagger project was donated to the OpenAPI Initiative, where it's now referred to as OpenAPI. Les deux noms sont utilisés indifféremment, mais OpenAPI est préféré.Both names are used interchangeably; however, OpenAPI is preferred. Il permet aux ordinateurs et aux utilisateurs de comprendre les fonctionnalités d’un service sans aucun accès direct à l’implémentation (code source, accès réseau, documentation).It allows both computers and humans to understand the capabilities of a service without any direct access to the implementation (source code, network access, documentation). L’un des objectifs est de limiter la quantité de travail nécessaire pour connecter des services dissociés.One goal is to minimize the amount of work needed to connect disassociated services. Un autre objectif est de réduire le temps nécessaire pour documenter un service avec précision.Another goal is to reduce the amount of time needed to accurately document a service.

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

Le cœur du Flow OpenAPI est la spécification — par défaut, un document nommé openapi.jssur.The core to the OpenAPI flow is the specification—by default, a document named openapi.json. Elle est générée par la chaîne d’outils OpenAPI (ou des implémentations tierces de celle-ci) en fonction de votre service.It's generated by the OpenAPI tool chain (or third-party implementations of it) based on your service. Elle décrit les fonctionnalités de votre API et comment y accéder avec HTTP.It describes the capabilities of your API and how to access it with HTTP. Elle gère l’interface utilisateur Swagger et est utilisée par la chaîne d’outils pour activer la découverte et la génération de code client.It drives the Swagger UI and is used by the tool chain to enable discovery and client code generation. 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. Cliquez sur un nom de méthode pour développer la section.Click a method name to expand the section. Ajoutez tous les paramètres nécessaires, puis cliquez sur essayer !.Add any necessary parameters, and click 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