Oh my God, Swagger API文档竟然可以这样写?
最好的总会在不经意间出现。
“
作为后端程序员,免不了与前端同事对接API, 一个书写良好的API设计文档可有效提高与前端对接的效率。
为避免联调时来回撕逼,今天我们聊一聊正确编写Swaager API文档的姿势。
基础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请求为例,细数这最基础Swagger文档的弊病:
[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?
没有约定请求的媒体类型,前端会不会给你另外一个surprise?
API 文档没有指示响应的媒体类型,前端以哪种姿势接收?
API文档没有指示响应的预期输出内容、状态码,前端会不会抓狂?
下文就来根治这些顽疾, 书写一个自述性、优雅的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注释:remarks
“
注意如果注释内容包含代码,可以使用Markdown的代码语法```,在注释里面优雅显示代码。
通过
Consumes
,Produces
特性指示action接收和返回的数据类型,也就是媒体类型。
“
Consumes、Produces是指示请求/响应支持的content-type的过滤器,位于Microsoft.AspNetCore.Mvc命名空间下。
通过
ProducesResponseType
特性指示API响应的预期内容、状态码
API文档显示如下:
这样的Swagger文档才正确表达了后端程序员的内心输出。
在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解决方案加载带xml注释的Swagger Json,需要更改xmlFile为特定HttpApi.xml或applicaiton.xml。
以上就是小码甲总结的书写Swagger文档的优雅姿势:
编写API 传值example
约束请求/响应 支持的媒体类型
指示API的预期输出内容、预期状态码
内容自述,格式工整,前端同事再也不会追着你撕逼了!
Oh my God, Swagger API文档竟然可以这样写?相关推荐
- swagger api文档_带有Swagger的Spring Rest API –创建文档
swagger api文档 使REST API易于使用的真正关键是好的文档. 但是,即使您的文档做得很好,您也需要设置公司流程的权利以正确,及时地发布它. 确保利益相关者按时收到是一回事,但是您也要负 ...
- swagger api文档_带有Swagger的Spring Rest API –公开文档
swagger api文档 创建API文档后,将其提供给涉众很重要. 在理想情况下,此发布的文档将足够灵活以解决任何最后的更改,并且易于分发(就成本以及完成此操作所需的时间而言). 为了使之成为可能, ...
- swagger 扫描java文档_推荐一款在运行时通过javadoc生成Swagger API文档的库
介绍 一般,我们使用Springfox生成swagger api文档,但Springfox不支持从javadoc中生成,只能通过注解的方式标注文档. 这样,当共享一些POJO类时,为了同时生成java ...
- 使用 Vscode 编写 HTML 文档竟然可以自动写代码(2)
作者简介 作者名:1_bit 简介:CSDN博客专家,2020年博客之星TOP5,蓝桥签约作者.15-16年曾在网上直播,带领一批程序小白走上程序员之路.欢迎各位小白加我咨询我相关信息,迷茫的你会找到 ...
- 聚合微服务中的 Swagger API 文档
没有做 API 文档聚合,访问每个服务的 API 文档都需要访问单独的 swagger-ui.html 页面,既然我们使用了微服务,就应该有统一的 API 文档入口,而 knife4j 有这方面的支持 ...
- SpringBoot 显示Swagger Api 文档
1. 配置pom文件,在pom文件中引入Swagger的相关依赖: <!-- swagger --> <dependency><groupId>com.githu ...
- CentOS 7 搭建swagger Api文档管理系统
1,系统环境 a,操作系统 CentOS Linux release 7.6.1810 (Core) 64位 b,安装Node.js的npm工具环境: # Node 官网已经把 linux 下载 ...
- 基于.NetCore3.1搭建项目系列 —— 使用Swagger做Api文档(上篇)
前言 为什么在开发中,接口文档越来越成为前后端开发人员沟通的枢纽呢? 随着业务的发张,项目越来越多,而对于支撑整个项目架构体系而言,我们对系统业务的水平拆分,垂直分层,让业务系统更加清晰,从而产生一系 ...
- 在ASP.NET Core Web API上使用Swagger提供API文档
我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页 ...
最新文章
- iometer硬盘测试工具附教程
- 自然语言处理中句子相似度计算的几种方法
- 过拟合和欠拟合以及相对应的解决办法
- jQuery中attr和prop方法的区别
- ssh mysql 警告_ssh 对数据表查询出错。警告: SQL Error: 1064, SQLState: 42000
- CollaDec 之前的三个SharePoint工具开源发布
- python中的pandas的两种基本使用_pandas中join()的两种应用方法
- C++3个汉诺塔递归问题
- 2019年python黑马_决心在2019年让Python成为您的朋友
- IDL读取TXT文件并写入二维数组中【转】
- sql server整表查询慢_这里有一个慢 SQL 查询等你来优化
- java 求百分比_java中计算百分比
- NLP笔记之文本聚类
- sht11的linux程序,SHT11温湿度传感器的proteus仿真与程序源码
- 宝塔面板防火墙安装和使用教程详解
- 通用能力-智力题专项练习
- C++制作“简单”小游戏
- 跨站点设置 Cookie
- http请求状态码有哪些?分别代表什么意思?
- 萌新的linux之旅27
热门文章
- 服务发现与健康监测框架Consul-DNS转发的应用
- 60个高质量的CSS、XHTML网页布局模板下载
- WPF企业内训全程实录(下)
- python倒三角形粉色填充笔的形状海龟_Python001-Turtle(海龟绘图)详解
- Macbook全系列详细分析及购机指南
- 三年级计算机击键要领教案,闽教版信息技术三上《下行键操作》教案
- matlab循环遍历数组_Matlab - 访问for循环中最大值的索引,并使用它从数组中删除值...
- 编译安装Centos7.2+Apache2.4.25+PHP7.2.10+Mysql5.6.16
- 中国HBase技术社区第五届MeetUp ——HBase技术解析及应用实践(深圳站)
- bondat蠕虫传播与对抗