利用Swashbuckle生成Web API Help Pages
2024-04-10 12:53:16
利用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注释都会写入到这个文件中。
个人博客
最新文章
- 如何用bat批处理编译swf项目
- MYSQL #1064错误
- C# 从入门到精通
- Windows下cmd的替代软件——PowerCmd
- asp.net 文件上传示例整理
- Nodejs v4.x.0API文档学习（2）Assert断言测试模块
- SPRING IN ACTION 第4版笔记-第四章ASPECT-ORIENTED SPRING-012-AOP总结
- mysql增量ID 启动值更改方法
- iOS开发——获取当前屏幕显示的viewcontroller
- List，map,Set区别
- iBatis.net技术实践
- centos6.5的开机自动部署出现unsupported hardware detected
- 带你深入理解STL之Vector容器
- [C++ Primer Plus] 第10章、对象和类（一）程序清单——辨析三个const
- Linux安装Tomcat-Nginx-FastDFS-Redis-Solr-集群——【第四集之安装Linux】
- ASP.NET页面之间传值的方式之QueryString（个人整理）
- python监控服务器的主备模式
- Java的背景、影响及前景
- Ubuntu下安装qq方法及疑难问题解决
- Centos安装Oracle数据库文本记录