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

Les différentes méthodes qui permettent d’utiliser une API web ne sont pas toujours simples à comprendre pour les développeurs.When consuming a Web API, understanding its various methods can be challenging for a developer. Swagger, également appelé OpenAPI, résout le problème de la génération de pages d’aide et de documentation qu’utilisent 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écouvrabilité des API.It provides benefits such as interactive documentation, client SDK generation, and API discoverability.

Cet article décrit les implémentations .NET Swagger 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’interface utilisateur 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 Swagger (swagger.json)Swagger specification (swagger.json)

Au cœur du flux Swagger se trouve la spécification Swagger, document nommé par défaut swagger.json.The core to the Swagger flow is the Swagger specification—by default, a document named swagger.json. Elle est générée par la chaîne d’outils Swagger (ou des implémentations tierces) en fonction de votre service.It's generated by the Swagger 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 l’exemple d’une spécification Swagger, réduite par souci de concision :Here's an example of a Swagger specification, reduced for brevity:

{
   "swagger": "2.0",
   "info": {
       "version": "v1",
       "title": "API V1"
   },
   "basePath": "/",
   "paths": {
       "/api/Todo": {
           "get": {
               "tags": [
                   "Todo"
               ],
               "operationId": "ApiTodoGet",
               "consumes": [],
               "produces": [
                   "text/plain",
                   "application/json",
                   "text/json"
               ],
               "responses": {
                   "200": {
                       "description": "Success",
                       "schema": {
                           "type": "array",
                           "items": {
                               "$ref": "#/definitions/TodoItem"
                           }
                       }
                   }
                }
           },
           "post": {
               ...
           }
       },
       "/api/Todo/{id}": {
           "get": {
               ...
           },
           "put": {
               ...
           },
           "delete": {
               ...
   },
   "definitions": {
       "TodoItem": {
           "type": "object",
            "properties": {
                "id": {
                    "format": "int64",
                    "type": "integer"
                },
                "name": {
                    "type": "string"
                },
                "isComplete": {
                    "default": false,
                    "type": "boolean"
                }
            }
       }
   },
   "securityDefinitions": {}
}

Interface utilisateur de SwaggerSwagger UI

L’IU Swagger est une interface utilisateur web qui fournit des informations sur le service, à l’aide de la spécification Swagger générée.Swagger UI offers a web-based UI that provides information about the service, using the generated Swagger 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’interface utilisateur web ressemble à ceci :The web UI looks like this:

Interface utilisateur de Swagger

Chaque méthode d’action publique dans vos contrôleurs peut être testée à partir de l’interface utilisateur.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 Try it out! .Add any necessary parameters, and click Try it out!.

Exemple de test GET Swagger

Notes

La version de l’interface utilisateur 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