这是一个创建于 2298 天前的主题，其中的信息可能已经有所发展或是发生改变。
我们公司之前使用 word 维护了一份 api 文档，每次接口有更新都要手动的更新文档，而且项目有几个后端，经常会有人忘记更新。。。
最近想集成 Swagger 来生成 api 文档，写了一个 demo，感觉好丑。。。
难道是我集成的方式不对，想问问大家有没有什么更简洁的办法
 |
1
panpanpan 2018-08-07 16:42:13 +08:00
再丑也比用 Word 管理的好看吧。
你也可以只使用 swagger 生成的 json 数据，放到这 http://petstore.swagger.io/ 去看，界面好看多了，也可以在内网自己搭一个 |
 |
2
cysroad OP @panpanpan
http://ww.sinaimg.cx/005zWjpngy1fu187xjgy7j30td0g9jsk.jpg 确实比 word 好多了，可能我还不是很熟悉 Swagger 写成这样了。。 |
|
3
panpanpan 2018-08-07 16:48:07 +08:00
|
 |
4
pkaq 2018-08-07 16:48:25 +08:00
如果十年前我会这样说 ：word。。。。excel 不好用？
|
 |
5
TommyLemon 2018-08-07 16:54:34 +08:00
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 支持下吧，谢谢^_^ |
|
6
TommyLemon 2018-08-07 16:55:18 +08:00
@TommyLemon 右侧向上滚动就能看到，在自动生成的代码下方
|
 |
7
sunsulei 2018-08-07 16:58:24 +08:00
@TommyLemon 你这推广也太多了。。。
|
 |
8
d18 2018-08-07 17:07:14 +08:00
swagger 挺好，既可以作为文档，又可以在线调试当 postman 用。
|
|
9
TommyLemon 2018-08-07 17:23:20 +08:00
@sunsulei 哈哈，不推广没人知道啊，
你看这个项目没怎么推广就 22 个 Star，还包括今天增加的 2 个。 github。com/TommyLemon/APIJSONAuto 再说这种相关的帖子，我推广下对自己和别人都有好处啊。 另一个作者发帖推广： www.v2ex.com/t/471479#reply8 |
 |
10
jalena 2018-08-07 17:36:01 +08:00
先不说好不好，感觉臃肿~
|
 |
11
someonedeng 2018-08-07 17:37:01 +08:00
这么些个注解怼上去。。难看点正常 233
|
 |
12
xsir 2018-08-07 17:44:44 +08:00
我用 swagger editor 写感觉还行
|
 |
13
limuyan44 2018-08-07 17:47:03 +08:00 via Android
前阵子准备换上这个，但是用完代码真的很丑陋后来我放弃了
|
 |
14
holonunu 2018-08-07 17:52:52 +08:00
很不错的，可以定义样式
|
 |
16
6IbA2bj5ip3tK49j 2018-08-07 18:19:20 +08:00
@TommyLemon
你回复里全是强行推广。你都开始用。代替.了，估计是被 V2 提示多次回复包含同一 URL 了吧。珍惜 ID。 而且你这项目和这帖子有个屁的联系 1，需要楼主把原来的东西全扔掉，上你那套只能对数据库 CRUD 的脚手架。 2，不是所有的后端都是 xxxx 管理系统。 ---------------------------------------------- 不知道 LZ 用的语言，如果是 java 的话，可以看看 springfox 如果 controller 的 method 以及 request parameter 命名比较良好的话，可以省掉很多手工劳动。 |
 |
17
kifile 2018-08-07 18:22:55 +08:00
springfox +1，不用维护文档的感觉很棒，虽然感觉前端同学也从来不看
|
 |
18
my3157 2018-08-08 01:51:46 +08:00
你可能需要的是这个 https://github.com/Rebilly/ReDoc
|
 |
19
bayker 2018-08-08 08:30:58 +08:00
一直用 swagger,不用维护文档，前端有能接受。
|
 |
20
thinkmore 2018-08-08 09:54:18 +08:00
可以通过 swagger 产生的 json api 生成 html 格式的文档，带目录的哪种，这种比较方便。
如果是需要自动更新的话，可以跑一个任务去自动更新生成 |
 |
21
checkZH 2018-08-14 11:36:24 +08:00
apidoc
|
Select Language