利用Swashbuckle生成Web API Help Pages

这系列文章是参考了.NET Core文档和源码，可能有人要问，直接看官方的英文文档不就可以了吗，为什么还要写这些文章呢？

原因如下：

官方文档涉及的内容相当全面，属于那种大而全的知识仓库，不太适合初学者，很容易让人失去重要，让人掉入到具体的细节之中。对于大多数人来讲开发语言只是工具，程序员都有一个通病，就是死磕工具，把工具学深。我认为在工具上没有必要投入太多时间，以能高效地完成日常的工作项目为准即可。要需求驱动学习，你需要什么学什么。如果你学的新技术新特性只是屠龙之技或者只需要用到的时候去查一下即可的话，这种死磕这又有什么用。没有必要花120%的时间去学100%的知识，你只需要花20%的时间去学习80%的知识就可以了，剩下的等实际的项目中用到的时候去查就可以了,工具只是工具，不是工作本身。目前基本所有的文章都是基于Windows平台的Visual Studio IDE来介绍的。而我用的是一台Mac，所以我将基于Mac平台的Visual Studio Code讲解适合我们实际项目中遇到的知识。还有一点，就是这是我个人的学习总结。

这系列文章就是让你去花20%的时间去学80%的东西，剩下的20%再去看官方文档。

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

个人博客

我的个人博客