利用Swashbuckle生成Web API Help Pages

利用Swashbuckle生成Web API Help Pages

本文将通过Swagger的.NET Core的实现封装工具Swashbuckle来生成上一篇-《创建ASP.NET Core Web API》的帮助文档。

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 查看描述终结点的文档。

{
  "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描述信息

ConfigureSwaggerGen方法可以用来添加作者、版权、描述等信息。

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注释都会写入到这个文件中。

个人博客

我的个人博客