Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。swagger不仅能提供接口文档,还能提供简单的传参测试。Swagger是用于描述REST API 的语言不可知的规范。Swagger项目捐赠给了OpenAPI Initiative,现在称为OpenAPI。这两个名称可以互换使用。但是,首选OpenAPI。本文主要简单介绍认识Swagger/OpenAPI、Swashbuckle.AspNetCore及NSwag。

1、Swagger规范(swagger.json)

Swagger流的核心是Swagger规范-默认情况下,名为swagger.json的文档。它是由Swagger工具链(或其第三方实现)根据您的服务生成的。它描述了您的API的功能以及如何通过HTTP访问它。它驱动Swagger UI,工具链使用它来启用发现和客户端代码生成。这是Swagger规范的示例,为简洁起见,将其简化:

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

2、Swagger UI

Swagger UI提供了一个基于Web的UI,它使用生成的Swagger规范提供有关服务的信息。Swashbuckle和NSwag都包含Swagger UI的嵌入式版本,因此可以使用中间件注册调用将其托管在ASP.NET Core应用程序中。Web UI如下所示:

httpsfileaionlifexyzsourcedownloadid5e760902dc72d90263e632bd

可以从UI中测试控制器中的每种公共操作方法。单击方法名称以展开该部分。添加任何必要的参数,然后单击“Try it out”。

httpsfileaionlifexyzsourcedownloadid5e760943dc72d90263e632be

3、Swashbuckle.AspNetCore和NSwag

Swashbuckle.AspNetCore:一个开放源代码项目,用于为ASP.NET Core Web API生成Swagger文档。

NSwag:另一个开源项目,用于生成Swagger文档并将Swagger UIReDoc集成到ASP.NET Core Web API中。另外,NSwag提供了为API生成C#和TypeScript客户端代码的方法。

参考文档:https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-3.1

相关文档:

ASP.NET Core NSwag的使用配置及示例

ASP.NET Core Swashbuckle的使用配置及示例

ASP.NET Core Swashbuckle的使用自定义UI及扩展配置示例