V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
cysroad
V2EX  ›  Java

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

  •  1
     
  •   cysroad · 2018-08-07 16:37:27 +08:00 · 8040 次点击
    这是一个创建于 2329 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

    21 条回复    2018-08-14 11:36:24 +08:00
    panpanpan
        1
    panpanpan  
       2018-08-07 16:42:13 +08:00
    再丑也比用 Word 管理的好看吧。
    你也可以只使用 swagger 生成的 json 数据,放到这 http://petstore.swagger.io/ 去看,界面好看多了,也可以在内网自己搭一个
    cysroad
        2
    cysroad  
    OP
       2018-08-07 16:44:32 +08:00
    @panpanpan
    http://ww.sinaimg.cx/005zWjpngy1fu187xjgy7j30td0g9jsk.jpg
    确实比 word 好多了,可能我还不是很熟悉 Swagger 写成这样了。。
    panpanpan
        3
    panpanpan  
       2018-08-07 16:48:07 +08:00
    @cysroad 原来你是说的代码丑啊。我还以为你说的 swagger-ui 界面丑。这个好像无解,或者你可以用 VO 去接收参数,把 @apiParam 放到 VO 里面去。
    pkaq
        4
    pkaq  
       2018-08-07 16:48:25 +08:00
    如果十年前我会这样说 :word。。。。excel 不好用?
    TommyLemon
        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 支持下吧,谢谢^_^
    TommyLemon
        6
    TommyLemon  
       2018-08-07 16:55:18 +08:00
    @TommyLemon 右侧向上滚动就能看到,在自动生成的代码下方
    sunsulei
        7
    sunsulei  
       2018-08-07 16:58:24 +08:00
    @TommyLemon 你这推广也太多了。。。
    d18
        8
    d18  
       2018-08-07 17:07:14 +08:00
    swagger 挺好,既可以作为文档,又可以在线调试当 postman 用。
    TommyLemon
        9
    TommyLemon  
       2018-08-07 17:23:20 +08:00
    @sunsulei 哈哈,不推广没人知道啊,
    你看这个项目没怎么推广就 22 个 Star,还包括今天增加的 2 个。
    github。com/TommyLemon/APIJSONAuto

    再说这种相关的帖子,我推广下对自己和别人都有好处啊。
    另一个作者发帖推广:
    www.v2ex.com/t/471479#reply8
    jalena
        10
    jalena  
       2018-08-07 17:36:01 +08:00
    先不说好不好,感觉臃肿~
    someonedeng
        11
    someonedeng  
       2018-08-07 17:37:01 +08:00
    这么些个注解怼上去。。难看点正常 233
    xsir
        12
    xsir  
       2018-08-07 17:44:44 +08:00
    我用 swagger editor 写感觉还行
    limuyan44
        13
    limuyan44  
       2018-08-07 17:47:03 +08:00 via Android
    前阵子准备换上这个,但是用完代码真的很丑陋后来我放弃了
    holonunu
        14
    holonunu  
       2018-08-07 17:52:52 +08:00
    很不错的,可以定义样式
    xipushi
        15
    xipushi  
       2018-08-07 18:13:22 +08:00
    你可以不写 @ApiParam 注解啊.@Api 的注解都不是必须的。
    6IbA2bj5ip3tK49j
        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 命名比较良好的话,可以省掉很多手工劳动。
    kifile
        17
    kifile  
       2018-08-07 18:22:55 +08:00
    springfox +1,不用维护文档的感觉很棒,虽然感觉前端同学也从来不看
    my3157
        18
    my3157  
       2018-08-08 01:51:46 +08:00
    你可能需要的是这个 https://github.com/Rebilly/ReDoc
    bayker
        19
    bayker  
       2018-08-08 08:30:58 +08:00
    一直用 swagger,不用维护文档,前端有能接受。
    thinkmore
        20
    thinkmore  
       2018-08-08 09:54:18 +08:00
    可以通过 swagger 产生的 json api 生成 html 格式的文档,带目录的哪种,这种比较方便。

    如果是需要自动更新的话,可以跑一个任务去自动更新生成
    checkZH
        21
    checkZH  
       2018-08-14 11:36:24 +08:00
    apidoc
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   951 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 19:17 · PVG 03:17 · LAX 11:17 · JFK 14:17
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.