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