With swagger2, maintain API documentation is in trouble? The return value can not be explained? --- or useless method?

Before talking to colleagues and some technical document interface this matter, and referred to the swagger, the feedback received from these:

"A lot of trouble! Interfaces and code documentation to be coupled together."

"Field descriptions to write a few times! A change to change a lot of places!"

"Request parameter want to describe clearly write a bunch of stuff !!"

 

I also looked under the control methods to be so descriptions of each parameter, do a little humanity ah!

@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})

And for the return value, it is most often example encapsulates a response object, similar to:

@Data
public class RespData{
	public static final int Success = 1;
	public static final int Error = 0;
	
	private int status;
	private Object datas = "";
	private Object meta = "";
	
	public RespData(int status, Object datas) {
		this.status = status;
		if(status == Success){
			this.datas = datas;
		}else{
			this.meta = datas;
		}
	}
	
	public RespData(Exception e){
		this.status = Error;
		this.meta = e.getMessage();
	}
	
}

The result is finally generated document interface, the return value for this description:

Front-end personnel when reading the document, it should look like this right 

 

I probably talk about how they used it: (do not need to do that much work, sometimes because they do not really familiar with how other people will only see how to use)

 

My environment: SpringBoot Mybatis PLUS + 2.1 + 3.1.0 + Swagger2 Lombok

First of all, as far as possible into the reference used to carry objects, either get or post method, this is a good habit, you can also do some package, I am here to encapsulate a PageQuery objects, there are pageNo, pageSize two Integer (compared to you All methods require paging query parameters are put these two variables to be elegant and some of it?)

Then, since it is encapsulated object, you can not have a big lump @ApiImplicitParams it! With this comment: @ApiModelProperty.

@Data
public class ProductQuery extends PageQuery{

	@ApiModelProperty(value = "商品类型ID")
	private Long typeId;
	
}

In addition to transform what data is returned objects, support for generics allowed

public class RespDataT<T>{
	public static final int Success = 1;
	public static final int Error = 0;
	
	private int status;
	private T datas ;
	private Object meta = "";
	
    public RespDataT(T datas) {
		this.datas = (T)datas;
		this.status =Success;
	}
	public RespDataT(int status, T datas) {
		this.status = status;
		if(status == Success){
			this.datas =(T) datas;
		}else{
			this.meta = datas;
		}
	}
	public RespDataT(Exception e){
		this.status = Error;
		this.meta = e.getMessage();
	}
}

Ah, look at how to write the controller

        @ApiOperation("商品列表")
	@GetMapping(path = "/list")
	@ResponseBody
	public RespDataT<IPage<Product>> list(ProductQuery query) {
		try{
			
			Page<Product> page = new Page<>(query.getPage(),query.getPageSize());
			IPage<Product> datas = productMapper.getProductPage(page,query);
			
			return new RespDataT<IPage<Product>>(datas);
		}catch (Exception e) {
			LOGGER.error(e.getMessage(),e);
			return new RespDataT<IPage<Product>>(e);
		}
	}

Wherein, IPage Mybatis plus paging parameters is provided, Product Mybatis plus generated by the entity data table.

Further mention that, Mybatis plus code generator, is automatically added Swagger2 of annotation! !

GlobalConfig gc = new GlobalConfig();
gc.setSwagger2(true);

The generated code: 

 

Such generated entities have been added @ApiModelProperty, that is to say: you just written annotation database tables, fields, explain your API documentation is also ok.

 

Finally, look at the resulting document looks like a Swagger

Request section contains the parameters we have inherited paging parameters, plus new entity attributes. (Page objects I did not add @ApiModelProperty)

And then return the data of the document:

 

 

Later encountered field adjustment, mybatis plus regenerate what entity code on it.

(Anyway, the generated code, projects as much as possible not to manually change, and easy maintenance)