Swagger如此难用，你们竟然还在用？

已于 2023-10-20 15:38:55 修改
阅读量2.1k 收藏 4
点赞数 1
分类专栏： 接口文档管理工具 文章标签： java 经验分享
于 2021-08-09 23:57:30 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/isFuong/article/details/119549690
版权

随便一个接口文档管理工具都能秒Swagger，更别提接口文档管理工具中的佼佼者YApi了，接下来就来对比下二者的优缺点。

关于Swagger

遇到的问题

  1. 在想要联调接口时，如果接口还没发布甚至还没开发，则需要等待接口开发完成后才能进行联调
  2. 对于开发接口的人员，想要生成一份接口文档，需要先引入swagger的jar包，在定义接口时，需要额外编写大量注解及参数。在接口开发完成并发布上线前，对于其他人来说该接口定义是完全不可见的，只能等待！
  3. 当接口开发完成后，如果需要添加一些备注及说明，只能修改项目源代码并重新发布上线
  4. 接口文档的更改无法溯源，难以固化这份“标准”，一旦出现前后端接口参数不一致的问题，容易产生争执、扯皮

其他共识问题

  1. 代码侵入性太强、项目中需要依赖与业务无关的jar包、需要编写大量与业务无关的注解和参数，增加开发成本，降低代码可读性
  2. 文档的展示依赖于项目的部署启动。不便于前端脱离后端进行接口调试，降低开发效率
  3. 不支持全局的接口文档的统一管理和维护，没有一个文档中心
  4. 不支持mock数据，不便于前端调试复杂接口，影响前端开发效率及质量
  5. 不支持权限管理，对于接口文档的访问没有项目、角色、人员级别的权限管控
  6. 不支持测试人员进行接口自动化测试
  7. 不支持导出备份
  8. 添加文档备注很不方便，需要更改源代码，不能添加截图备注/不适合添加大段的备注等
  9. 对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse 注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map),就无法实现给每一个返回字段的说明。如果将所有的返回结果都是用对象封装，然后添加注解，这又是一个非常大的工作量
  10. 界面巨丑，排版不人性化

YApi的特性功能

以上swagger不支持的功能yapi都可实现
  1. 接口文档统一可视化管理，形成接口对接规范，前后端及测试人员对一切接口的调试验证皆以Yapi文档定义为准
  2. 方便查找接口，不用再到处找接口，去yapi上找就行了
  3. 对项目零侵入、零耦合，只需编写业务代码即可，至于必要的接口注释，可使用idea模板一键生成，极大提高生产力
  4. 支持多种文档生成方式：导入、手动编写、根据注释自动生成
支持swagger、har、postman、json等格式文件的导入，配合idea插件，更可识别注释自动生成文档到yapi平台
  1. 支持导出为JSON、swaggerJOSN、Markdown、html、doc等多种文件格式，便于存档及导入到其他（自动化测试、接口管理）工具
  2. 丰富的插件、开放接口、钩子函数，可结合实现高度个性化功能
  3. 支持细粒度权限管理、第三方登录、LDAP登录
  4. 支持邮件通知
  5. 支持mock数据，真正实现前后端分离开发
  6. 支持自动化测试
  7. 支持查看接口文档变更历史
  8. UI界面美观、页面功能丰富、页面交互人性化
  9. 支持全功能私有化部署

官方文档：YApi 接口管理平台

如果打不开此文档可在host文件配置：185.199.111.153 hellosean1025.github.io

github地址：GitHub - YMFE/yapi: YApi 是一个可本地部署的、打通前后端及QA的、可视化的接口管理平台

基本信息YAPISwagger
star数/fork数/commit数21.8k / 3.8k / 57476.8k / 2k / 3978
初版本时间~最新版时间2017.10.08~2021.06.252011.10.17~2021.06.28
开发语言后端： koa mongoose 前端： react reduxjava
使用方百度、阿里巴巴、腾讯、京东、今日头条、快手、美团、携程、去哪儿、艺龙、新浪...Haiwei Cloud, IBM, Yelp, VMWare, Atlassian等
文档中文文档、相关资料很多英文文档完善，中文资料少
维护团队去哪儿网smartbear

总结：

Swagger优点：

  • 开发语言为java，从开发语言上来讲，进行二次开发成本相对YApi较低
  • 无需独立部署，只需要随应用启动即可
  • 对C语言支持较好，在C语言项目无需添加注解即可生成文档

YApi缺点：

  • 开发语言非java，从开发语言上来讲，进行二次开发相对Swagger较高
  • 需要独立部署，不能随应用启动

更新：2022-09-06

最近发现了比二者更好用的接口文档管理工具：Apifox，有时间也写一篇对比评测

isFuong
关注
  • 1
    点赞
  • 踩
  • 4
    收藏
    觉得还不错? 一键收藏
  • 4
    评论
专栏目录
抱怨Swagger不好用？好吧我换一个好用的
码农小胖哥
05-10 2039
最近前端们一直反映Swagger看接口信息非常不爽，于是我花了俩小时把Swagger干掉，用上了传说中更好用的YApi。今天就简单分享一下心得体会。Swagger与YApi其实我个人认为S...
浅谈swagger优缺劣势，以及替代品
qq_32527449的博客
01-26 2461
平时不太关注的swagger, 最近拿到一个优化需求， 需要把springboot 项目启动优化一下，于是开始了打怪埋坑的道路。 先将讲一讲swagger 的原理实现以及优缺点。 springfox-swagger简介 签于swagger的强大功能，Java开源界大牛spring框架迅速跟上，它充分利用自已的优势，把swagger集成到自己的项目里，整了一个spring-swagger，后来便演变成springfox。springfox本身只是利用自身的aop的特点，通过plug的方式把...
Swagger的原理及应用详解（十二）
最新发布
凛鼕将至的博客
07-08 814
Swagger（OpenAPI Specification）是一个功能强大的框架和规范，它通过自动化生成文档、提供详细的API描述以及支持调用和可视化等功能，极大地简化了API的设计、构建、使用和理解过程。无论是在企业内部还是跨企业的API合作中，Swagger都发挥着重要的作用。 本文将跟随《Swagger的原理及应用详解（十一）》的进度，继续介绍Swagger。希望通过本系列文章的学习，您将能够更好地理解Swagger的内部工作原理，掌握Swagger的使用技巧，以及通过合理的设计完成
JApiDocs入门教程
Java旅途
06-22 8787
今天给大家安利一款接口文档生成器——JApiDocs。 swagger想必大家都用过吧，非常方便，功能也十分强大。如果要说swaager有什么缺点，想必就是注解写起来比较麻烦。如果我说有一款不用写注解，就可以生成文档的工具，你心动了吗？他就是我们今天的主角——JApiDocs。 下面我们一起来看看如何使用！ 一、添加依赖 <dependency> <groupId>io.github.yedaxia</groupId> <artifactId>japi
都说Swagger很好用，今天亲身体验了一把，结果是这样
goody9807的专栏
03-26 1929
Swagger最近比较火，大家是否推荐使用呢？对于接口文档输出都使用什么工具
Swagger也不好用了，API文档还得是Apipost
m0_72491330的博客
02-15 308
平时常用的生成接口文档的工具大多都是Swagger，而Swagger是国外研发的工具，上手较为复杂且繁琐，而且也需要很多代码才能生成，还需要对应的Swagger Editor和SwaggerUI，这两者都需要从Github上下载源码，将其部署到本地Tomcat服务器上，然后通过浏览器访问即可，其他的部署方式也较为繁琐。而Apipost不用这么麻烦，调试接口或进行API设计的时候自动就直接生成了接口文档，而且数据都实时同步，不用担心需求频繁被修改而文档也需要一直维护，简单好用且容易上手。
还在用 Swagger？试试这款神器，功能真心强大！
Java技术栈，分享最主流的Java技术
10-22 152
介绍 smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。 你只需要按照java-doc标准编写注释， smart-doc就能帮你生成一个简易明了的Markdown、HTML5、Postman、Collection2.0+、OpenAPI 3.0+的文档。 目前使用者 科大讯飞 小米 一加 顺丰 特点 零注解、
还在用Swagger？试试这款零注解侵入的API文档生成工具
m0_63437643的博客
08-14 76
** * 显示状态(0,1) * @ignore */ private Integer showStatus;{ "errorCodeDictionaries": [{ //错误码列表设置 "title": "title", "enumClassName": "com.macro.mall.tiny.common.api.ResultCode", //错误码枚举类 "codeField": "code", //错误码对应字段 "descField": "message" //错误码描述对应字段 }] }
springmvc集成swagger实现接口文档自动化生成
热门推荐
liufei198613的博客
07-01 1万+
一直苦于文档整理工作，因为这是一个很无聊的工作，偶然在网上看到了swagger这东西，感觉不错，于是动手集成了一下，眼前一亮           Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagge
轻量级Web框架应用_第三周(下)
Robin_John的博客
09-21 1177
第三周_下分支Gradle和MavenSwaggerSwagger简介下载Swagger配置Swagger修改login接口启动项目提交Bug记录 分支 安装了git这么强大的版本控制系统，却不好好利用着实可惜；在开发之前我们先来创建个分支吧！ 在开发中，将每次的操作都放在master分支中不是一个明智的选择，master分支里一般存放的是一个完整的，稳定的版本； 首先，我们可以使用git ch...
Spring Boot进阶(44)：如何为你的项目开启HTTPS协议加密传输，让你的网站更加安全？
**My Coding Family**
09-06 2231
如何项目上配置以HTTPS协议访问？这你必须会啊！
Spring Boot入门(29)：如何实现Spring Boot的热部署，让你的代码修改能够立即生效？
**My Coding Family**
03-10 5104
springboot如何实现热部署配置？这篇文手把手教你，一秒学会！
Spring Boot进阶(39)：如何让你的日期时间格式在全局生效，解决Jackson序列化时间问题
**My Coding Family**
05-23 1739
SpringBoot之Jackson配置全局时间日期格式，如果你不会，我可以教你。
还在用Swagger？我推荐这款零代码侵入的接口管理神器
m0_67645544的博客
05-04 278
静态的 Swagger 们跟不上频繁变更的代码 “为什么改了这个没告诉我”,“实际功能和文档上说的不一样啊”。这些话大家做开发的想必耳朵都听出老茧了。真不是故意的，有时候任务比较急，就先改了代码，想着以后再同步文档，然后就给忘了。项目更新又全靠社交软件通知，人一多难免有一两个没及时沟通到的。确实给合作的小伙伴带来麻烦，但说实话开 发也挺委屈的。 这些问题产生的主要原因是，当前大部分研发团队的工作流程是这样的： 旧协作模式 这种模式带来的问题是： 1. Swagger ，postman ，
还在用Swagger生成接口文档？我推荐你试试它…..
文章中资料均可获取，有需要请添加yunduoa2019即可
06-15 608
推荐阅读：阿里P8架构师谈：工作1-5年的Java工程师，怎样提高核心竞争力 阿里架构师直言：“没有实战都是纸上谈兵”！Redis实战PDF分享 奋发图强半年多，终于四面阿里如愿拿到心仪offer定级P7 JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。 编写和维护API文档这个事情，对于后端程序员来说，是一件恼人但又不得不做的事情，我们都不喜欢写文档，但除非项目前后端代码都是自己写的，否则A...
Swagger强大，好用，易上手的API文档工具
yuchenai的博客
01-04 1545
Swagger强大的API文档工具 1.Swagger是什么？ Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTfu风格的web服务。 简单点来讲就是，swagger是一款可以根据restful风格生成的接口开发文档，并且支持做测试的一款中间软件。官网地址 htt...
Swagger API 接口文档生成工具的利与弊
Mrqiang9001
04-03 8331
Swagger API 接口文档生成工具的利与弊 作为Java后台工程师其中的一员，作者深知众多的开发者没有写接口文档的习惯。尤其是一些新手，他们只想着把功能实现、和前端开发者把接口调试通就好了，没有考虑到后期的项目维护。当他们接受一个旧项目，进行二次开发的时候，突然发现看别人的代码太难了，既没有注释，也没有接口文档，看懂一块代码逻辑要大半天，时间都浪费在了读懂旧代码上了。 为了能够偷懒(不写接口文档)，开发者发明了一种神器— Swagger ...
swagger太好用了，你会吗
qq_45109643的博客
03-14 248
在Swagger UI中，你可以直接测试API端点，包括GET、PUT、POST、DELETE等请求方法，很方便地查看请求的参数、响应头和响应体，并且可以方便地测试和调试API端点。通过使用Swagger提供的命令行工具和集成接口，你可以根据API的注释自动生成API文档。在Swagger UI中，你可以方便地查看生成的API文档，测试和调试API，以及获取API的详细信息。在你的应用程序中，你需要在API端点方法的代码中添加Swagger注释，这些注释描述了API的参数、响应和其他元数据。
在Web API项目中，用Swagger描述API接口的例子？
05-16
以下是一个使用Swagger描述API接口的Web API项目的示例： ```csharp using System.Collections.Generic; using Microsoft.AspNetCore.Mvc; namespace MyWebApi.Controllers { [ApiController] [Route("[controller]")] public class UsersController : ControllerBase { /// <summary> /// 获取所有用户 /// </summary> /// <returns>用户列表</returns> [HttpGet] [ProducesResponseType(typeof(IEnumerable<User>), 200)] public IActionResult GetAllUsers() { return Ok(new List<User> { new User { Id = 1, Name = "Alice" }, new User { Id = 2, Name = "Bob" } }); } /// <summary> /// 获取指定用户 /// </summary> /// <param name="id">用户ID</param> /// <returns>用户信息</returns> [HttpGet("{id}")] [ProducesResponseType(typeof(User), 200)] [ProducesResponseType(404)] public IActionResult GetUser(int id) { var user = new User { Id = id, Name = "Alice" }; if (user == null) { return NotFound(); } return Ok(user); } /// <summary> /// 添加用户 /// </summary> /// <param name="user">用户信息</param> /// <returns>添加结果</returns> [HttpPost] [ProducesResponseType(typeof(User), 201)] [ProducesResponseType(400)] public IActionResult AddUser(User user) { if (user == null) { return BadRequest(); } user.Id = 3; // 模拟分配ID return CreatedAtAction(nameof(GetUser), new { id = user.Id }, user); } /// <summary> /// 更新用户 /// </summary> /// <param name="id">用户ID</param> /// <param name="user">用户信息</param> /// <returns>更新结果</returns> [HttpPut("{id}")] [ProducesResponseType(204)] [ProducesResponseType(400)] [ProducesResponseType(404)] public IActionResult UpdateUser(int id, User user) { if (user == null || user.Id != id) { return BadRequest(); } // 更新用户信息 return NoContent(); } /// <summary> /// 删除用户 /// </summary> /// <param name="id">用户ID</param> /// <returns>删除结果</returns> [HttpDelete("{id}")] [ProducesResponseType(204)] [ProducesResponseType(404)] public IActionResult DeleteUser(int id) { // 删除用户信息 return NoContent(); } } public class User { public int Id { get; set; } public string Name { get; set; } } } ``` 在上面的示例中，我们使用了 `[ApiController]` 和 `[Route]` 特性来定义控制器和路由。其中，`[ApiController]` 告诉 ASP.NET Core 这是一个 Web API 控制器，并使用默认的行为，例如自动模型绑定和验证。`[Route]` 特性指定了控制器的路由前缀。 每个操作方法都有一个 HTTP 动词特性，例如 `[HttpGet]`，指定了该方法对应的 HTTP GET 请求。我们还使用了`[ProducesResponseType]` 特性，用于指定操作方法的返回类型及其 HTTP 状态码。这些信息可以帮助 Swagger 自动生成 API 文档。 在上面的示例中，我们使用了标准的 HTTP 状态码和响应模型。但是，你也可以使用自定义的状态码和响应模型，只需在`[ProducesResponseType]` 特性中指定即可。 当你启用 Swagger 后，你可以在浏览器中访问 `http://localhost:<port>/swagger` 查看自动生成的 API 文档。
评论 4
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值