Swagger使用介绍二之为Controller中参数添加字段说明

• 回顾

上文介绍了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类型字段说明