利用Swashbuckle生成Web API Help Pages
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注释都会写入到这个文件中。
【本文为专栏作者“朱成林”的原创稿件，转载请联系原作者】
戳这里，看该作者更多好文
亿华云