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

V2EX = way to explore

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

现在注册

已注册用户请登录

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

先说下背景

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

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

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

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

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

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

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

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

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

问题来了

是我做错了什么吗？如果不是我的错，这是不是所谓开源项目的坑？
到底是什么原因导致我用起来这么困难？
有没有过来人说说 Springfox 生成 Swagger 这个东西正确的用法？
有没有其他的方式能够直接生成 API 文档？

API

文档

springfox

swagger

3 条回复 • 2018-06-11 10:01:36 +08:00

Cbdy

2018-06-10 12:40:37 +08:00 via Android

参考一下这个例子，springfox 有官方文档的
github.com/cbdyzj/boot

lxy

2018-06-10 20:59:09 +08:00

没太明白你的需求，用起来还行，基本按照这样写的 https://github.com/swagger-api/swagger-core/wiki/Annotations

zhaogaz

2018-06-11 10:01:36 +08:00

@lxy 我昨天查了很久之后终于醒悟了。

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

springfox 那个作者，觉得 swagger-core 的侵入性太强了，虽然用的是 swagger 的注解包，但是很多功能都没实现，我试了一部分，很多功能不生效的。