Oh my God, Swagger API文档竟然可以这样写?
最好的总会在不经意间出现。
作为后端程序员,免不了与前端同事对接API, 一个书写良好的API设计文档可有效提高与前端对接的效率。
为避免联调时来回撕逼,今天我们聊一聊正确使用Swaager的姿势。
基础Swagger用法
在ConfigureServices
配置Swagger文档,在Configure
启用中间件
// Install-Package Swashbuckle.AspNetCore 略
services.AddSwaggerGen(
options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "EAP API", Version = "v1" });
}
);
---
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "EAP API");
});
应用会在/Swagger
页面加载最基础的API文档。
以一个最简单的Post请求为例,细数这最基础SwaggerUI的弊病
[HttpPost]
public async Task<bool> AddHotmapAsync([FromBody] CreateHotmapInput createHotmapInput)
{
var model = ObjectMapper.Map<CreateHotmapInput, Hotmap>(createHotmapInput);
model.ProfileId = CurrentUser.TenantId;
return await _hotmaps.InsertAsync(model)!= null;
}
产生如图示SwaggerUI:
- Post请求的Payload字段值相对复杂,竟不给前端传值example?
- 没有指示前端请求的Content-Type,前端会不会给你另外一个surprise?
- 服务器没有指示响应的Content-Type,?
- 服务器没有指示响应的预期状态码,前端会不会抓狂?
下文就来根治这些顽疾, 书写一个自述性、优雅的API文档。
Swagger最佳实践
三下五除二,给出示例:
/// <summary>
/// 添加热力图
/// </summary>
/// <remarks>
/// Sample request:
/// ```
/// POST /hotmap
/// {
/// "displayName": "演示名称1",
/// "matchRule": 0,
/// "matchCondition": "https://www.cnblogs.com/JulianHuang/",
/// "targetUrl": "https://www.cnblogs.com/JulianHuang/",
/// "versions": [
/// {
/// "versionName": "ver2020",
/// "startDate": "2020-12-13T10:03:09",
/// "endDate": "2020-12-13T10:03:09",
/// "offlinePageUrl": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // 没有绑定图片和离线网页的对应属性传 null
/// "pictureUrl": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
/// "createDate": "2020-12-13T10:03:09"
/// }
/// ]
/// }
///```
/// </remarks>
/// <param name="createHotmapInput"></param>
/// <returns></returns>
[Consumes("application/json")]
[Produces("text/plan")]
[ProducesResponseType(typeof(Boolean), 200)]
[HttpPost]
public async Task<bool> AddHotmapAsync([FromBody] CreateHotmapInput createHotmapInput)
{
var model = ObjectMapper.Map<CreateHotmapInput, Hotmap>(createHotmapInput);
model.ProfileId = CurrentUser.TenantId;
return await _hotmaps.InsertAsync(model)!=null;
}
- 通过给API添加XML注释
注意如果注释内容包含代码,可以使用Markdown的代码语法```,在注释里面优雅显示代码.
- 通过
Consumes
,Produces
特性指示action接收和返回的数据类型,也就是媒体类型。
Consumes、Produces是指示请求/响应支持的content types的过滤器,位于Microsoft.AspNetCore.Mvc命名空间下。
- 通过
ProducesResponseType
特性指示服务器响应的预期内容和状态码
API输出的结果如下:
这样的SwaggerUI才正确表达了后端程序员的内心输出。
在Swagger文档上显示注释
- 生成XML注释文档
在项目上[右键]-[属性]-[生成标签页]-[勾选XML文档文件];
或者直接在项目csproj文件--[PropertyGroup]添加<GenerateDocumentationFile>true</GenerateDocumentationFile>
- 在
AddSwaggerGen
方法添加下行,启用注释文件
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{this.GetType().Assembly.GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
opt.IncludeXmlComments(xmlPath);
这里啰嗦一下,如果是Abp Vnext解决方案,因为API是定义在HttpApi项目/Application项目,故我们要加载Abp Vnext解决方案的Swagger Json,需要指示xmlFile为HttpApi.xml或者applicaiton.xml
以上就是小码甲总结的书写Swagger文档的优雅姿势:
- 编写API 传值example
- 约束请求/响应 支持的媒体类型
- 指示API的预期输出内容、预期状态码
API自述,约束输入输出,前端同事再也不会追着你撕逼了!
Oh my God, Swagger API文档竟然可以这样写?的更多相关文章
- 添加swagger api文档到node服务
swagger,一款api测试工具,详细介绍参考官网:http://swagger.io/ ,这里主要记录下怎么将swagger api应用到我们的node服务中: 1.任意新建node api项目, ...
- xadmin引入drf-yasg生成Swagger API文档
一.安装drf-yasg: 由于django-rest-swagger已经废弃了 所以引入了drf-yasg pip install drf-yasg 安装install drf-yasg库 http ...
- Swagger API文档
Swagger API文档集中化注册管理 接口文档是前后端开发对接时很重要的一个组件.手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的 ...
- swagger api 文档框架
<其他教程:https://www.cnblogs.com/FlyAway2013/p/7510279.html> 先看看swagger的生态使用图: 其中,红颜色的是swaggger官网 ...
- Swagger API文档集中化注册管理
接口文档是前后端开发对接时很重要的一个组件.手动编写接口文档既费时,又存在文档不能随代码及时更新的问题,因此产生了像swagger这样的自动生成接口文档的框架.swagger文档一般是随项目代码生成与 ...
- swagger api文档添加jwt授权配置
最近写的swagger文档,要加jwt授权,所以几经google终于搞定了,简简单单几行配置如下: securityDefinitions: APIKey: type: apiKey name: Au ...
- JavaWeb项目中集成Swagger API文档
1.增加依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-sw ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
- Core Web API上使用Swagger提供API文档
在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的AP ...
随机推荐
- K尾相等数(模运算)
Description 从键盘输入一个自然数K(K>1),若存在自然数M和N(M>N),使得K^M^和K^N^均大于或等于1000,且他们的末尾三位数相等,则称M和N是一对"K尾 ...
- kali 系列学习02 - 被动扫描
被动扫描是指目标无法察觉的情况下进行信息收集,注意有经验的渗透工程师会在信息收集上花费整个测试过程一半以上的时间,信息量太大,需要自动化的信息收集工具. 一.借鉴<kali linux2 网络渗 ...
- Stream流的这些操作,你得知道,对你工作有很大帮助
Stream流 Stream(流)是一个来自数据源的元素队列并支持聚合操作: 元素是特定类型的对象,形成一个队列. Java中的Stream并不会存储元素,而 是按需计算. 数据源 流的来源. 可以是 ...
- 去年去阿里面试,面试官居然问我Java类和对象,我是这样回答的!
1.谈谈你对Java面向对象的理解? 面向对象就是把构成问题的事务分解成一个个对象,建立对象的目的不是一个步骤,而是为了描述一个事务在解决问题中的行为.类是面向对象的一个重要概念,类是很多个具有相同属 ...
- jQuery 第十章 ajax 什么是回调地狱 优化回调地狱
回调地狱 什么是回调地狱,回调函数,一个嵌套着一个,到最后,缩略图成了 一个三角形, 造成了可阅读性差,可阅读性差就代表代码的可维护性 和 可迭代性差,最后还有一个就是可扩展性差. 也不符合设计模式的 ...
- Elasticsearch搜索资料汇总
Elasticsearch 简介 Elasticsearch(ES)是一个基于Lucene 构建的开源分布式搜索分析引擎,可以近实时的索引.检索数据.具备高可靠.易使用.社区活跃等特点,在全文检索.日 ...
- python 如何跳过异常继续执行
使用try...except...语句,类似于if...else...,可以跳过异常继续执行程序,这是Python的优势 用法如下: 1 2 3 4 5 6 try: # 可能会 ...
- T147403 「TOC Round 4」吃,都可以吃
若不考虑 \(m\) 的限制,打表可以发现: 当 \(p=2^n\left(n>1\right)\) 时,最大的 \(f_i\) 是 \(5\),有十个 \(i\) 的 \(f_i\) 是 \( ...
- 变更mysql的数据类型兼容小数测试
来吧 我也没想到有一天要做这个测试: 想分为这几步吧: 1.先看看mysql本身支不支持数据的变更 2.再看看mybatis能不能用int接受double和decimal 先看下mysql: alte ...
- 由OptionalLong想到的拆装箱问题
包装类型为null的时候时候拆箱会报空指针