Swagger问题记录

一、版本

springfox不要使用3.3.0，这个版本太高，和spring其他组件不兼容，swagger-ui.html页面都出不来，推荐使用2.9.2。

二、包扫描

页面出来了，但是显示：No operations defined in spec!。这说明你的配置有问题，swagger没有扫描到任何接口。

可以能原因一：

没有配置.apis(RequestHandlerSelectors.basePackage("xxx.controller"))，据我个人测试，在2.9.2版本，如果不配置apis(接口包名)，配置其他的如.paths(PathSelectors.regex("/cms/*"))、.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))都是没有卵用的。

可以能原因二：

配置apis(接口包名)时，包名填写错误，并且一个Docket中配置错误会连累其他Docket。
.apis(RequestHandlerSelectors.basePackage("xxx.controller"))，如果xxx.controller这个包不存在，会导致后续其他Docket无法创建，哪怕其他Docket的配置正确也无法扫描。

三、调用方式

3.1 指明接口调用方式

接口一定要指明调用方式是POST还是GET或者其他，千万不要使用@RequestMapping又不指明调用方式，不然Swagger会生成一堆无用接口文档：

一般来说，使用PostMapping就能解决问题，如果确实需要支持多种调用方式，可以这样写：@RequestMapping(value="/login/name",method = {RequestMethod.POST,RequestMethod.GET})。

3.1 GET和RequestBody冲突

接口参数如果使用了@RequestBody接收，那么接口调用方式就不要使用GET，否则会报错：

TypeError: Failed to execute 'fetch' on 'Window': Request with GET/HEAD method cannot have body.

四、参数和返回值

4.1 参数

参数不要使用实体类，要为参数单独创建一个DTO类。
假如登录接口只需要username和password，用了实体类之后，实体类的其他参数也会被Swagger扫描成接口参数。

当然修改和新增之类的接口，想偷懒也是可以使用实体类的，但是不建议，因为参数会经常变动，实体类是不能根据参数变动的，只能根据数据库字段来变动。

4.2 返回值

返回值如果有修剪，就不要使用实体类，因为没修剪的其他字段也会被Swagger扫描成接口返回值，所以需要像参数一样创建一个单独的DTO。

五 基本注解：

接口