Swagger 的使用

Question

3.1 常用注解

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。 Swagger 使用的注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给 API 增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

• paramType：指定参数放在哪个地方
• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：说明参数的意思
• defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息

• code：数字，例如 400
• message：信息，例如"请求参数没填好"
• response：抛出异常的类

@ApiModel：描述一个 Model 的信息（一般用在请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）

• @ApiModelProperty：描述一个 model 的属性

3.2 案例

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

import io.swagger.annotations.ApiResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cache.ehcache.EhCacheCacheManager;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import cn.uni.app.config.controller.AppBaseController;
import cn.uni.app.service.MemberService;
import cn.uni.common.core.dto.ListDto;

@RestController
@RequestMapping("/member")
@Api(description = "用户相关操作")

/**
 * 用户控制类
 * @author Mark
 *
 */
public class MemberController extends AppBaseController {

	@Autowired
	private MemberService memberService;
	@Autowired
	private EhCacheCacheManager cacheManager;
	
	
	@GetMapping("/getQueryProcBiMainMj")
	@ApiOperation("存储过程查询省市医院服务能力数据")
	public ListDto<Map<String, Object>> getQueryProcBiMainMj(
			@ApiParam("开始时间")@RequestParam(defaultValue="2018-01-01")String sdate,
			@ApiParam("结束时间")@RequestParam(defaultValue="2018-12-31")String edate) {
		return memberService.getQueryProcBiMainMj(sdate,edate);
	}
	
	@GetMapping("/getQueryProcBiMainZy")
	@ApiOperation("存储过程查询省市医院出院人次和机构数")
	public ListDto<Map<String, Object>> getQueryProcBiMainZy(
			@ApiParam("开始时间")@RequestParam(defaultValue="2018-01-01")String sdate,
			@ApiParam("结束时间")@RequestParam(defaultValue="2018-12-31")String edate) {
		return memberService.getQueryProcBiMainZy(sdate,edate);
	}
	
	
	@GetMapping("/identifyCode")
	@ApiOperation("获取验证码")
	public void identifyCode(HttpServletResponse response, HttpServletRequest request) {
	
	}
}