利用Swashbuckle生成Web API Help Pages

[[189063]]

Swashbuckle简介

Swashbuckle有两个核心组件：

• Swashbuckle.SwaggerGen: 提供生成描述对象，方法，返回类型等JSON Swagger文档的功能。
• Swashbuckle.SwaggerUI: 一个Swagger UI工具的嵌入式版本，可以使用上面的文档来创建可定制化的Web API的功能描述，包含内置的公共方法的测试工具。

在middleware中添加并配置Swagger

首先,要将Swashbuckle添加到项目中的project.json：

"Swashbuckle": "6.0.0-beta902" 

然后在Configure方法中添加SwaggerGen到services集合中，接着在ConfigureServices方法中，允许中间件(middleware)为生成的JSON文档和SwaggerUI提供服务。

执行dotnet run命令，并导航到http://localhost:5000/swagger/v1/swagger.json 查看描述终结点的文档。

在middleware中添加并配置Swagger 
首先,要将Swashbuckle添加到项目中的project.json： 
 
"Swashbuckle": "6.0.0-beta902" 
然后在Configure方法中添加SwaggerGen到services集合中，接着在ConfigureServices方法中，允许中间件(middleware)为生成的JSON文档和SwaggerUI提供服务。 
 
 
 
执行dotnet run命令，并导航到http://localhost:5000/swagger/v1/swagger.json 查看描述终结点的文档。 
 
{ 
  "swagger": "2.0", 
  "info": { 
    "version": "v1", 
    "title": "API V1" 
  }, 
  "basePath": "/", 
  "paths": { 
    "/api/User": { 
      "get": { 
        "tags": [ 
          "User" 
        ], 
        "operationId": "ApiUserGet", 
        "consumes": [], 
        "produces": [ 
          "text/plain", 
          "application/json", 
          "text/json" 
        ], 
        "responses": { 
          "200": { 
            "description": "Success", 
            "schema": { 
              "type": "array", 
              "items": { 
                "$ref": "#/definitions/UserItem" 
              } 
            } 
          } 
        }, 
        "deprecated": false 
      }, 
      "post": { 
        "tags": [ 
          "User" 
        ], 
        "operationId": "ApiUserPost", 
        "consumes": [ 
          "application/json", 
          "text/json", 
          "application/json-patch+json" 
        ], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "item", 
            "in": "body", 
            "required": false, 
            "schema": { 
              "$ref": "#/definitions/UserItem" 
            } 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      } 
    }, 
    "/api/User/{id}": { 
      "get": { 
        "tags": [ 
          "User" 
        ], 
        "operationId": "ApiUserByIdGet", 
        "consumes": [], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "string" 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      }, 
      "put": { 
        "tags": [ 
          "User" 
        ], 
        "operationId": "ApiUserByIdPut", 
        "consumes": [ 
          "application/json", 
          "text/json", 
          "application/json-patch+json" 
        ], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "string" 
          }, 
          { 
            "name": "item", 
            "in": "body", 
            "required": false, 
            "schema": { 
              "$ref": "#/definitions/UserItem" 
            } 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      }, 
      "delete": { 
        "tags": [ 
          "User" 
        ], 
        "operationId": "ApiUserByIdDelete", 
        "consumes": [], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "string" 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      }, 
      "patch": { 
        "tags": [ 
          "User" 
        ], 
        "operationId": "ApiUserByIdPatch", 
        "consumes": [ 
          "application/json", 
          "text/json", 
          "application/json-patch+json" 
        ], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "item", 
            "in": "body", 
            "required": false, 
            "schema": { 
              "$ref": "#/definitions/UserItem" 
            } 
          }, 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "string" 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      } 
    }, 
    "/api/Values": { 
      "get": { 
        "tags": [ 
          "Values" 
        ], 
        "operationId": "ApiValuesGet", 
        "consumes": [], 
        "produces": [ 
          "text/plain", 
          "application/json", 
          "text/json" 
        ], 
        "responses": { 
          "200": { 
            "description": "Success", 
            "schema": { 
              "type": "array", 
              "items": { 
                "type": "string" 
              } 
            } 
          } 
        }, 
        "deprecated": false 
      }, 
      "post": { 
        "tags": [ 
          "Values" 
        ], 
        "operationId": "ApiValuesPost", 
        "consumes": [ 
          "application/json", 
          "text/json", 
          "application/json-patch+json" 
        ], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "value", 
            "in": "body", 
            "required": false, 
            "schema": { 
              "type": "string" 
            } 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      } 
    }, 
    "/api/Values/{id}": { 
      "get": { 
        "tags": [ 
          "Values" 
        ], 
        "operationId": "ApiValuesByIdGet", 
        "consumes": [], 
        "produces": [ 
          "text/plain", 
          "application/json", 
          "text/json" 
        ], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "integer", 
            "format": "int32" 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success", 
            "schema": { 
              "type": "string" 
            } 
          } 
        }, 
        "deprecated": false 
      }, 
      "put": { 
        "tags": [ 
          "Values" 
        ], 
        "operationId": "ApiValuesByIdPut", 
        "consumes": [ 
          "application/json", 
          "text/json", 
          "application/json-patch+json" 
        ], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "integer", 
            "format": "int32" 
          }, 
          { 
            "name": "value", 
            "in": "body", 
            "required": false, 
            "schema": { 
              "type": "string" 
            } 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      }, 
      "delete": { 
        "tags": [ 
          "Values" 
        ], 
        "operationId": "ApiValuesByIdDelete", 
        "consumes": [], 
        "produces": [], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "required": true, 
            "type": "integer", 
            "format": "int32" 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "Success" 
          } 
        }, 
        "deprecated": false 
      } 
    } 
  }, 
  "definitions": { 
    "UserItem": { 
      "type": "object", 
      "properties": { 
        "key": { 
          "type": "string" 
        }, 
        "name": { 
          "type": "string" 
        }, 
        "age": { 
          "format": "int32", 
          "type": "integer" 
        } 
      } 
    } 
  }, 
  "securityDefinitions": {} 
} 

该文档用来驱动Swagger UI，可以导航http://localhost:5000/swagger/ui来查看Swagger UI。

在UserController里面的每个方法都可以在该页面上通过点击”Try it out!”进行测试。

定制&扩展

API描述信息

services.ConfigureSwaggerGen(options => 
{ 
    options.SingleApiVersion(new Info 
    { 
        Version = "v1", 
        Title = "User Web API", 
        Description = "ASP.NET Core Web API", 
        TermsOfService = "None", 
        Contact = new Contact { Name = "Charlie Chu", Email = "charlie.thinker@aliyun.com", Url = "http://zhuchenglin.me/" }, 
        License = new License { Name = "The MIT License", Url = "http://zhuchenglin.me/" } 
    }); 
}); 

XML注释

通过在project.json添加“xmlDoc”: true来启用XML注释。

ApplicationBasePath获取该应用的根路径，它必须为XML注释设置一个完整的路径，生成的XML注释名称基于你的应用程序的名称。

注意这个界面是通过之前生成的JSON文件来驱动的，所有的这些API描述信息和XML注释都会写入到这个文件中。

【本文为51CTO专栏作者“朱成林”的原创稿件，转载请联系原作者】

戳这里，看该作者更多好文