在Java类中添加Swagger的注解即可生成Swagger接口文档,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用 @ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数的描述信息
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数的描述信息
@ApiImplicitParam属性:
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名 | |
value | 接收参数的意义描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
上边的属性后边编写程序时用到哪个我再详细讲解,下边写一个swagger的简单例子,我们在MerchantController中添加Swagger注解,代码如下所示:
@RestController
@Api(value="商户平台应用接口",tags = "商户平台应用接口",description = "商户平台应用接口")
public class MerchantController {
@org.apache.dubbo.config.annotation.Reference
MerchantService merchantService;
@ApiOperation(value="根据id查询商户信息")
@GetMapping("/merchants/{id}")
public MerchantDTO queryMerchantById(@PathVariable("id") Long id){
MerchantDTO merchantDTO = merchantService.queryMerchantById(id);
return merchantDTO;
}
@ApiOperation("测试")
@GetMapping(path = "/hello")
public String hello(){
return "hello";
}
@ApiOperation("测试")
@ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "string")
@PostMapping(value = "/hi")
public String hi(String name) {
return "hi,"+name;
}
}