建站
咨询
售后
建站咨询
利用Swashbuckle生成WebAPIHelpPages
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注释都会写入到这个文件中。
【本文为专栏作者“朱成林”的原创稿件，转载请联系原作者】
本文名称：利用Swashbuckle生成WebAPIHelpPages
文章分享：http://aqpgk.com/article/dpjhjod.html
