利用Swashbuckle生成Web API Help Pages

時間 2019-12-08

標籤利用 swashbuckle 生成 web api help pages 欄目 HTML 简体版

原文原文鏈接

利用Swashbuckle生成Web API Help Pages

本文將經過Swagger的.NET Core的實現封裝工具Swashbuckle來生成上一篇-《建立ASP.NET Core Web API》的幫助文檔。git

Swashbuckle簡介

Swashbuckle有兩個核心組件：github

Swashbuckle.SwaggerGen: 提供生成描述對象，方法，返回類型等JSON Swagger文檔的功能。
Swashbuckle.SwaggerUI: 一個Swagger UI工具的嵌入式版本，能夠使用上面的文檔來建立可定製化的Web API的功能描述，包含內置的公共方法的測試工具。

在middleware中添加並配置Swagger

首先,要將Swashbuckle添加到項目中的project.json：web

"Swashbuckle": "6.0.0-beta902"

而後在Configure方法中添加SwaggerGen到services集合中，接着在ConfigureServices方法中，容許中間件(middleware)爲生成的JSON文檔和SwaggerUI提供服務。json

執行dotnet run命令，並導航到http://localhost:5000/swagger/v1/swagger.json 查看描述終結點的文檔。api

{
  "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。app

在UserController裏面的每一個方法均可以在該頁面上經過點擊"Try it out!"進行測試。dom

定製&擴展

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/" }
    });
});