开发了一个方便写 Swagger 文档的项目

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

爱意满满的作品展示区。

这是一个创建于 1589 天前的主题，其中的信息可能已经有所发展或是发生改变。

一开始准备写个 API 项目，结果发现没有一个写 Swagger 方式文档的工具，不要提在代码里面用注释的方式生成 Swagger 文档，我觉得这种方式特别恶心。

所以我自己手动造了一个轮子，仓库：

已经实现 Github Action CI，编写 API，配合 Github Pages 实现自动更新文档。

7 条回复 • 2020-07-18 19:41:50 +08:00

cweijan

2020-07-17 10:10:28 +08:00

你这个的作用是啥? 在代码用注释生成文档是很好的方式, 我想你指的是注解

cai314494687

2020-07-17 10:12:52 +08:00

@cweijan #1 我指的是用注释的方式生成 Swagger API 文档，感觉 1 是自由度不够高，2 是注释的格式非常不友好，往往要写很长的一段注释，而且注释的内容是不能被 IDE 格式化的，我觉得非常不友好。

cai314494687

2020-07-17 10:14:53 +08:00

@cweijan #1 忘了说作用了，这个工具就是给你方便写 Swagger API 文档的，看看 openapi 目录就知道了。

cweijan

2020-07-17 10:21:14 +08:00

@cai314494687 看了下, 说实在并不看好, 接口如果发生变动, 就和文档不同步了, 如果用注释的方式就可以及时更新了
swagger 有 https://github.com/Willing-Xyz/RestDoc
yapi 有 https://plugins.jetbrains.com/plugin/index?xmlId=com.itangcent.idea.plugin.easy-yapi

cai314494687

2020-07-17 10:24:27 +08:00

@cweijan #4 不好意思，我不用 Java，我这个跟语言无关。

我这个只是一个小工具而已，我自己用起来方便，顺便分享给大家，大家用得着就更好了，用不着就算了，反正就花了 1 天时间开发的。

raaaaaar

2020-07-17 12:18:43 +08:00 via Android

我觉得把写接口文档和接口测试联系起来是比较好的方式，比如 postman 生成文档就不错，方便管理接口，也方便更新

yanshenxian

2020-07-18 19:41:50 +08:00

@raaaaaar +1 就喜欢这种无侵入的就是更耗费精力
如果是 java spring 有个 spring rest doc