利用Swashbuckle生成Web API Help Pages
来源:互联网 发布:ubuntu挂起怎么启动 编辑:程序博客网 时间:2024/06/05 05:36
利用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注释都会写入到这个文件中。
个人博客
我的个人博客
- 利用Swashbuckle生成Web API Help Pages
- Swashbuckle Swagger UI 用于 MVC web api
- 使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
- 利用SAP内置功能生成Search Help
- 利用SAP内置功能生成Search Help
- ASP.NET Web Pages (Razor) API Quick Reference
- ASP.NET Web API 2个步骤启用 Help 说明
- 利用Google API生成二维码
- 利用Google API生成二维码
- 利用API生成SO订单
- 利用javadoc生成API文档
- 利用javadoc生成API文档
- 利用eclipse生成API文档
- 利用api生成短地址
- PHP利用数据库生成API
- 翻译github help之Github Pages《what-is-github-pages》
- How to add help to Apex pages
- NS3搭建网络拓扑图
- C语言中的一些关键字(十三)
- IOS 单例模式详解
- mac下载xampp 安装wordpress 修改数据库密码
- CDC 类详解
- 利用Swashbuckle生成Web API Help Pages
- SSD代码阅读之sampler.cpp
- memcache查看节点状态
- Retrofit2 源码解析
- 【Hadoop】数据处理----MapReduce
- Matlab Tricks(二十三)—— 保存图像到 pdf
- 总结 Tarjan的一些应用
- 微信公众号开发中遇到的问题——支付回调,分享,获取openId
- Android数据的四种存储方式