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

问各位一个关于 Springfox 生成 Swagger 文档的问题,

  •  
  •   zhaogaz · 2018-06-10 12:32:19 +08:00 · 2675 次点击
    这是一个创建于 2118 天前的主题,其中的信息可能已经有所发展或是发生改变。

    先说下背景

    之前公司 API 文档混乱不堪,维护困难,我推荐了 Swagger,希望能采用 Open API 规范来写文档。

    但是技术经理也没分清楚,他找到了 Springfox 那个工具,可以在 Spring 项目中生成 API 文档。

    我司最近的新 SpringBoot 项目,技术经理让我把这个东西配置上。


    然后我就开始做这个事了。看下官网的 Reference 就开始了。

    现在我用这个工具,感觉非常反常规操作。

    配置的地方有预期的想法,但是没有生效。也不知道怎么查怎么回事。

    没有细粒度的排除,导致输出的 API 文档多了很多东西

    Security 方面,也没有找到 Http Method 的匹配,只找到了 path 的匹配。单独配置 @ApiKeyAuth。。。那个注解也没有生效,不知道去哪找原因

    官网也没有输出一个包含注释的 doc 文档。javadoc,虽然代码里面有注释。

    问题来了

    1. 是我做错了什么吗?如果不是我的错,这是不是所谓开源项目的坑?
    2. 到底是什么原因导致我用起来这么困难?
    3. 有没有过来人说说 Springfox 生成 Swagger 这个东西正确的用法?
    4. 有没有其他的方式能够直接生成 API 文档?
    3 条回复    2018-06-11 10:01:36 +08:00
    Cbdy
        1
    Cbdy  
       2018-06-10 12:40:37 +08:00 via Android   ❤️ 1
    参考一下这个例子,springfox 有官方文档的
    github.com/cbdyzj/boot
    lxy
        2
    lxy  
       2018-06-10 20:59:09 +08:00   ❤️ 1
    没太明白你的需求,用起来还行,基本按照这样写的 https://github.com/swagger-api/swagger-core/wiki/Annotations
    zhaogaz
        3
    zhaogaz  
    OP
       2018-06-11 10:01:36 +08:00
    @lxy 我昨天查了很久之后终于醒悟了。

    你给的那个文档基本没有参考性,因为 springfox-swagger 和 swagger-core 完全是两码事。

    springfox 那个作者,觉得 swagger-core 的侵入性太强了,虽然用的是 swagger 的注解包,但是很多功能都没实现,我试了一部分,很多功能不生效的。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5362 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 28ms · UTC 09:13 · PVG 17:13 · LAX 02:13 · JFK 05:13
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.