2024 年 5 个 Java REST API 框架
OpenAPI vs Swagger：哪个更适合您的API文档设计
2024-05-13
Open API 即开放 API，所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列API开放出去，供第三方开发者使用。
Swagger 则是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新，让部署管理和使用功能强大的 API 变得十分简单。
那么对于开发者来说，哪个更适合API文档设计呢？
一、对比二者在数据传输的差距
OpenAPI 是规范的正式名称。它提供了一套标准的API接口，让不同的业务系统可以通过这些接口进行交互和数据共享。也就是说开发者可以使用OpenAPI 完成自动化的文档信息填入，免于繁杂的输入程序。
以海外仓WMS业务为例，其他上游系统可以通过OpenAPI与海外仓进行数据交互和信息的传递。而传统的操作系统中，用户要推送数据，必须先从电商平台或者电商ERP中手动导出业务数据，然后再登录海外仓OMS，根据导入模板去填写业务数据。安装OpenAPI 的渠道可分为两种，一种是用户端搭建，开发者可以登陆谷仓平台，进行API设计。
开放平台的用户端又被分为API文档、接入指南/最佳实践和控制中心/工作台。其中API文档和接入指南一般都是直接对外开放的，访问相关URL就可以直接访问，不会做权限的控制。而控制中心/工作台则需要注册成为了开发者，登陆后，登录账号和密码后才可以访问，里面一般包含了自己的个人信息，接入的APP，还有一些接口调用日志，消息通知等；另一种是后台管理端的搭建，相比较之下，针对技术部分的内容，一些API的调用可能比较敏感，需要做费用的计算，调用次数的限制，日志的统计，还有异常的监控等，所以这些都需要在后台管理端去完成。
Swagger则是实现规范的工具，是与用于实现OpenAPI规范的一些最著名，使用最广泛的工具相关联的名称。比如Swagger编辑器、Swagger UI、Swagger Codegen等。通过使用Swagger，开发者可以有效地设计和文档化REST API，提高API的可读性和可维护性，同时为其他开发者、前端团队和API消费者提供一个清晰和准确的API参考。
开发者只需要下载“npm install swagger-jsdoc swagger-ui-express –save”代码，进而启动Swagger JSDoc以自动生成API文档，确保把apis的路径设置成包含有注释的API文件所在的路径，并在路由文件或控制器文件中添加JSDoc注释。就可以自动定义模型，如User对象，（具备id、username和email属性）。启动Node.js应用后，通过访问http://localhost:3000/api-docs来查看Swagger UI。Swagger UI会为API提供一个交互式的用户界面，使得调用者可以无需编写代码就能测试API的各个端点。
对比之下，OpenAPI更倾向于在已有的数据版面上，实现不同平台间的信息传输，帮助开发者自动化生成数据信息，减少沟通时间；而Swagger作为一种工具，具有多样性和可编辑性的客店，能够帮助开发者实现是设计、构建、记录和使用文档的功能。通过使用Swagger，开发者可以定义API的结构，确保API的稳定性，并生成协作所需的文档。
二、对比二者在企业场景中应用的差距
若说二者的基本功能只能满足单一化、简单化的使用需求的话，那么随着科学技术的发展，各大互联网企业将其开发应用在各自的内部程序中。
以阿里云的OpenAPI为例。阿里云不同于传统操作系统，因此，旗下的OpenAPI主要是用来进行云资源管理或数据传输的，操作对象都是用户资产，除了常规的身份管理、权限管理外，对企业来说还要服务于运维、财务、法务、监管等部门。开发者可以登录官网，进行文档设计，需要将切分后的文档列表向量化并上传到文档库。文档的向量化算法为创建知识库CreateDocumentCollection接口指定的算法。并用Java描述该 CodeSample 执行结果。
Swagger由开放源代码，免费和市售工具共同组成，不管是技术工程师，还是街头智能产品经理都可以配置各自都喜欢的API效果。正因为其应用范围广，一旦出现内部使用错误等情况，如曾经Swagger UI >=3.14.1 < 3.38.0版本受 XSS 影响出错， GitLab为后来的存储型XSS给出了$2000的赏金奖励。
从二者在企业场景中的应用上看，二者的运用范围均十分广泛，但OpenAPI在企业中的应用条件更为严苛，且受到管辖；Swagger的应用适用于个人，开发者可以按照自己想要的效果进行自由设计。
三、对比二者在适用范围内的权限限制
二者背后的社区范围并不相同。OpenAPI Initiative是一个开放的，与供应商无关的组织，更倾向于个体化、多元化，不受任何人管辖。只要开发者需要发展或利用其API开发中的规范，就可以随时加入使用。正是因为没有统一规范，该社区开发者无法赚取高额的酬金，但能获得该组织对规范做出贡献的成员进行列表表彰。开发者可以通过在GitHub上分享想法和反馈，或参加每月在世界各地举行的许多OAS聚会，了解到与组织相关的更多信息。
Swagger工具则拥有自己的独立社区，它致力于帮助改进某些现有Swagger项目，并引入新的想法和功能要求。Swagger社区背后有一家主导团队——SmartBear Software团队。该团队是一家私人持有的信息技术公司，专业从事软件开发，软件测试和应用性能监控（APM）。他们也投资于开源Swagger工具的开发，但也受到世界各地成千上万Swagger用户的贡献的推动。
从二者的适用范围上看，OpenAPI Initiative更倾向于开发者自主开发，纯粹是为一种概念而组织起来的社区；Swagger工具背后则有独立运营的公司，使用时出现问题还能找到相应的解决办法。
参考链接：
https://mp.weixin.qq.com/s/PPbCzl556pWOxQwm_4KPqA
https://mp.weixin.qq.com/s/zsBcikZpkeMzFxvzj1gmaw
https://mp.weixin.qq.com/s/5QJR1dU2JTg9z8peLwEgIw
https://api.aliyun.com/api-tools/demo/gpdb/62f80edc-5d96-4aaf-b158-5ed5fbec8203
内容关键字