[[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專欄作者“朱成林”的原創稿件，轉載請聯系原作者】

戳這里，看該作者更多好文