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。

五 基本注解：

接口

@Api(tags="用户管理")
@Controller
@RequestMapping(value = "/user")
public class UserController{

方法

	@ApiOperation(value = "用户列表",notes="获取所有用户信息",response = User.class)
	@RequestMapping(value = "/list",method=RequestMethod.GET)
	@ResponseBody
	public JSONObject getList(HttpServletRequest request,@PathVariable Integer lockId){
		return getData(userService.getList());
	}

参数

	@ApiOperation(value = "添加用户")
	@RequestMapping(value = "/add",method=RequestMethod.POST)
	@ResponseBody
	public JSONObject add(HttpServletRequest request,@ApiParam(value="用户信息")User user){

	@ApiOperation(value = "分页查询用户列表",response = User.class)
	@ApiImplicitParams({
    	@ApiImplicitParam(name = "pageNum", value = "页码", 
                         required = true, type = "Integer"),
    	@ApiImplicitParam(name = "pageSize", value = "每页条数", 
                         required = true, type = "Integer"),
    })
	@RequestMapping(value = "/pageList",method=RequestMethod.POST)
	@ResponseBody
	public JSONObject getPageList(HttpServletRequest request,@ApiParam(value="用户信息，查询条件")User user){

@ApiImplicitParams和@ApiParam区别

@ApiImplicitParams用在方法上，@ApiParam用在参数上。
@ApiImplicitParams用来描述方法上未申明的参数，@ApiParam用来描述方法上申明的参数。

数据模型

@ApiModel(value="用户信息",description = "用户对象实体")
@Data
public class User implements Serializable {
	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "用户ID，唯一标识")
	private Integer id;
	@ApiModelProperty(value = "用户类型 1、管理员 2、普通用户")
	private Integer type;
}