- 回顾
上文介绍了Swagger如何生成API文档--https://blog.csdn.net/shangcunshanfu/article/details/100838137,本篇介绍一下如何在API文档上为参数添加说明。
- 添加头信息
import cn.hgd11.swagger.success.entity.TestEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author :尚村山夫
* @date :Created in 2019/9/14 23:14
* @modified By:
*/
@RestController
@RequestMapping("test3")
@Api(tags = "测试3")
public class Test3Controller {
@ApiImplicitParams({
@ApiImplicitParam(name = "Authorization", value = "认证Token", required = true, dataType = "String",paramType = "header")
})
@GetMapping
@ApiOperation("测试方法1") // 用户对该接口进行说明的注解
public TestEntity testEntity(){
return new TestEntity();
}
}
将@ApiImplicitParam注解的paramType参数指定为header,该参数会告诉Swagger这是一个头信息。
点进@ApiImplicitParam查看paramType参数
/**
* The parameter type of the parameter.
* <p>
* Valid values are {@code path}, {@code query}, {@code body},
* {@code header} or {@code form}.
*/
String paramType() default "";
会发现,该参数支持五种类型,header即表示头信息。添加完该参数,API文档展现如下
对于有些添加了认证的系统来说,该参数可以在头信息中添加Token认证。将需要的Token添加到该参数中,即可向服务器发送请求。
- 添加键值对参数
import cn.hgd11.swagger.success.entity.TestEntity;
import io.swagger.annotations.*;
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;
/**
* @author :尚村山夫
* @date :Created in 2019/9/14 23:14
* @modified By:
*/
@RestController
@RequestMapping("test3")
@Api(tags = "测试3")
public class Test3Controller {
@ApiImplicitParams({
@ApiImplicitParam(name = "Authorization", value = "认证Token", required = true, dataType = "String",paramType = "header"),
})
@GetMapping
@ApiOperation("测试方法1") // 用户对该接口进行说明的注解
public TestEntity testEntity(
@RequestParam(value = "id") @ApiParam(value = "用户ID") Integer id,
@RequestParam(value = "name") @ApiParam(value = "用户名称") String name
){
return new TestEntity();
}
}
代码中的@ApiParam即是参数说明,添加该参数后,API文档展现如下:
- 添加键值对参数的别一种方法
import cn.hgd11.swagger.success.entity.TestEntity;
import io.swagger.annotations.*;
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;
/**
* @author :尚村山夫
* @date :Created in 2019/9/14 23:14
* @modified By:
*/
@RestController
@RequestMapping("test3")
@Api(tags = "测试3")
public class Test3Controller {
@ApiImplicitParams({
@ApiImplicitParam(name = "Authorization", value = "认证Token", required = true, dataType = "String",paramType = "header"),
@ApiImplicitParam(name = "id", value = "用户ID", dataType = "integer",paramType = "query"),
@ApiImplicitParam(name = "name", value = "用户姓名", dataType = "String",paramType = "query"),
})
@GetMapping
@ApiOperation("测试方法1") // 用户对该接口进行说明的注解
public TestEntity testEntity(
@RequestParam(value = "id") Integer id,
@RequestParam(value = "name") String name
){
return new TestEntity();
}
}
前面讲到@ApiImplicitParam的paramType属性有五个类型,其中一个是query,这个参数就是告诉Swagger这里有一个键值对的参数。这里的name属性要和参数名一致,value属性即是对参数的说明。
不过请看userId参数的类型,本来是integer类型,但是被解析成了ref,这里没找到原因。
其实本人比较习惯用第一种键值对的传参方式,直接对应于某一个参数,比较直接。
- 实体参数
对于POST请求或PUT请求,通常用传入一个实体类型的参数,如User对象,这时候怎么对User实体中的每一个属性进行参数说明呢?看以下代码:
实体1
/**
* @author :尚村山夫
* @date :Created in 2019/8/13 22:55
* @modified By:
*/
@ApiModel(description = "测试实体")
public class TestEntity {
@ApiModelProperty(value = "名称")
private String name;
@ApiModelProperty(value = "ID")
private Integer id;
@ApiModelProperty(value = "内部实体")
private TestEntity2 testEntity2;
public TestEntity2 getTestEntity2() {
return testEntity2;
}
public void setTestEntity2(TestEntity2 testEntity2) {
this.testEntity2 = testEntity2;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
}
实体2
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
* @author :尚村山夫
* @date :Created in 2019/8/13 22:55
* @modified By:
*/
@ApiModel(description = "测试实体2")
public class TestEntity2 {
@ApiModelProperty(value = "名称2")
private String name;
@ApiModelProperty(value = "ID2")
private Integer id;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
}
对实体添加@ApiModel注解,对实体中的每一个属性添加@ApiModelProperty注解,Controller代码如下:
import cn.hgd11.swagger.success.entity.TestEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
/**
* @author :尚村山夫
* @date :Created in 2019/9/14 23:14
* @modified By:
*/
@RestController
@RequestMapping("test3")
@Api(tags = "测试3")
public class Test3Controller {
@ApiImplicitParams({
@ApiImplicitParam(name = "Authorization", value = "认证Token", required = true, dataType = "String",paramType = "header"),
})
@PostMapping
@ApiOperation("测试方法1")
public TestEntity testEntity(
@RequestBody TestEntity testEntity
){
return new TestEntity();
}
}
展现如下:
诈一看有一点点乱,如果你是一名程序员而不是UI,请不要纠结于此。
在此做一个说明,GET请求是不支持接受@RequestBody参数是
到此其实有一个问题,如果要传入的实体是JSONObject类型,并没有一个实体类供我们添加@ApiModel及@ApiModelProperty怎么办呢,请参考https://blog.csdn.net/shangcunshanfu/article/details/100840152Swagger使用介绍三之为Controller中参数添加JSONObject类型字段说明