大家有用过 Swagger 生成 api 文档么

[cysroad]

我们公司之前使用 word 维护了一份 api 文档，每次接口有更新都要手动的更新文档，而且项目有几个后端，经常会有人忘记更新。。。

最近想集成 Swagger 来生成 api 文档，写了一个 demo，感觉好丑。。。

难道是我集成的方式不对，想问问大家有没有什么更简洁的办法

[panpanpan]

再丑也比用 Word 管理的好看吧。
你也可以只使用 swagger 生成的 json 数据，放到这 http://petstore.swagger.io/ 去看，界面好看多了，也可以在内网自己搭一个

[cysroad]

@panpanpan
http://ww.sinaimg.cx/005zWjpngy1fu187xjgy7j30td0g9jsk.jpg
确实比 word 好多了，可能我还不是很熟悉 Swagger 写成这样了。。

[panpanpan]

@cysroad 原来你是说的代码丑啊。我还以为你说的 swagger-ui 界面丑。这个好像无解，或者你可以用 VO 去接收参数,把 @apiParam 放到 VO 里面去。

[pkaq]

如果十年前我会这样说 ：word。。。。excel 不好用？

[TommyLemon]

Swagger 配置确实繁琐，如果配置不详细效果又不好（名称、类型、默认值都是必要的）
可以试试 APIJSONAuto，一行代码都不用写，直接用数据库表和字段属性自动生成文档哦

2. User
说明:
用户公开信息表。
对安全要求高，不想泄漏真实名称。对外名称为 User

字段:
名称 | 类型 | 最大长度| 详细说明
id | Long | 15 | 唯一标识
sex | Integer | 2 | 性别：0-男 1-女
name | String | 20 | 名称
tag | String | 45 | 标签
head | String | 300 | 头像 url
contactIdList | List | 不限 | 联系人 id 列表
pictureList | List | 不限 | 照片列表
date | Timestamp | 不限 | 创建日期

一刷新网页或改了 BaseURL 就会刷新文档，永不过时。

在线演示：
apijson.cn
项目源码：
github.com/TommyLemon/APIJSONAuto
创作不易，GitHub 右上角点 Star 支持下吧，谢谢^_^

[TommyLemon]

@TommyLemon 右侧向上滚动就能看到，在自动生成的代码下方

[sunsulei]

@TommyLemon 你这推广也太多了。。。

[d18]

swagger 挺好，既可以作为文档，又可以在线调试当 postman 用。

[TommyLemon]

@sunsulei 哈哈，不推广没人知道啊，
你看这个项目没怎么推广就 22 个 Star，还包括今天增加的 2 个。
github。com/TommyLemon/APIJSONAuto

再说这种相关的帖子，我推广下对自己和别人都有好处啊。
另一个作者发帖推广：
www.v2ex.com/t/471479#reply8

[jalena]

先不说好不好，感觉臃肿~

[someonedeng]

这么些个注解怼上去。。难看点正常 233

[xsir]

我用 swagger editor 写感觉还行

[limuyan44]

前阵子准备换上这个，但是用完代码真的很丑陋后来我放弃了

[holonunu]

很不错的，可以定义样式

[xipushi]

你可以不写 @ApiParam 注解啊.@Api 的注解都不是必须的。

[6IbA2bj5ip3tK49j]

@TommyLemon
你回复里全是强行推广。你都开始用。代替.了，估计是被 V2 提示多次回复包含同一 URL 了吧。珍惜 ID。

而且你这项目和这帖子有个屁的联系
1，需要楼主把原来的东西全扔掉，上你那套只能对数据库 CRUD 的脚手架。
2，不是所有的后端都是 xxxx 管理系统。


----------------------------------------------

不知道 LZ 用的语言，如果是 java 的话，可以看看 springfox
如果 controller 的 method 以及 request parameter 命名比较良好的话，可以省掉很多手工劳动。

[kifile]

springfox +1，不用维护文档的感觉很棒，虽然感觉前端同学也从来不看

[my3157]

你可能需要的是这个 https://github.com/Rebilly/ReDoc

[bayker]

一直用 swagger,不用维护文档，前端有能接受。

[thinkmore]

可以通过 swagger 产生的 json api 生成 html 格式的文档，带目录的哪种，这种比较方便。

如果是需要自动更新的话，可以跑一个任务去自动更新生成