swagger2(knife4j) 注解说明

一、引入maven依赖，代码如下：

        <!-- swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- knife4j接口文档 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

二、创建Swagger配置依赖，代码如下：

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {

    private static final String VERSION = "1.0.0";


    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                //分组名称
                .groupName("开发版本")
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                //指定接口包所在路径
                .apis(RequestHandlerSelectors.basePackage("com.dami.provider.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/doc.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文档标题
                .title("xxx-后台服务API接口文档")
                //简介(描述)
                .description("后台API接口明细")
                //服务URL
                .termsOfServiceUrl("https://blog.csdn.net/leaf__yang/article/details/126221094")
                //联系人信息
                .contact(new Contact("leaf", "localhost:8080/doc.html", "[email protected]"))
                //版本
                .version(VERSION)
                .build();
    }


    /**
     * knife4j官方配置如下
     * @return
     */
    /*@Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("xxx-后台服务API接口文档")
                        .description("后台API接口明细")
                        .termsOfServiceUrl("https://blog.csdn.net/leaf__yang/article/details/126221094")
                        .contact(new Contact("leaf", "localhost:8080/doc.html", "[email protected]"))
                        .version("1.0.0")
                        .build())
                .groupName("开发版本")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.dami.provider.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }*/

}

三、swagger2 注解的整体说明

3.1 请求类的描述

注解	说明
@Api	对请求类的说明

3.1.1 @Api 请求类的说明

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

 3.1.2 @Api 的其他属性配置

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols	协议类型，如: http, https, ws, wss
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

3.2 方法和方法参数的描述

注解	说明
@ApiOperation	方法的说明
@ApiImplicitParams	方法参数的说明；
@ApiImplicitParam	用于指定单个参数的说明。

 3.2.1 @ApiOperation：方法的说明

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

3.2.2 @ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

3.3 方法的响应状态的描述

注解	说明
@ApiResponses	方法返回值的说明 ；
@ApiResponse	用于指定单个参数的说明。

 3.3.1 @ApiResponses、@ApiResponse：响应状态状态的说明

@ApiResponses：响应状态的说明。是个数组，可包含多个 @ApiResponse
	@ApiResponse：每个参数的说明


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

3.4 对象的描述

注解	说明
@ApiModel	用在JavaBean类上，说明JavaBean的 整体用途
@ApiModelProperty	用在JavaBean类的属性上面，说明此属性的的含议

3.4.1 @ApiModel：对象的整体说明

@ApiModel 经常用于请求的入参对象和 响应返回值对象的描述。

    入参是对象，即 @RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
    返回值是对象，即 @ResponseBody 时，用于返回值对象的描述。

3.4.2 @ApiModelProperty：对象中每个参数的说明

@ApiModelProperty 用于每个属性上面，说明属生的含义。

3.4.3 对象使用注解示例，如下：

1）入参是对象，即 @RequestBody 时， 用于封装请求

@Data
@ApiModel(value = "EbgStocksTVO", description = "前端請求实体类参数")
public class EbgStocksTVO extends BaseClass {

    @ApiModelProperty(value = "Plane", required = true)
    String plant;

    @ApiModelProperty(value = "MATERIAL_RANGE")
    List<EbgStocksMaterialTBO> mlist;

    @ApiModelProperty(value = "STORAGE_RANGE")
    List<EbgStocksStorageTBO> slist;
}

2）返回值是对象，即 @ResponseBody 时，用于返回值对象的描述

@ApiModel(value = "ResultVo", description = "响应参数说明")
public class ResultVO {

	/**
	 * 响应码
	 */
	@ApiModelProperty(value = "响应码(0:失败,1:成功)", required = true)
	private Integer code;

	/**
	 * 提示信息
	 */
	@ApiModelProperty(value = "提示信息", required = true)
	private String message;

	/**
	 * 结果数据
	 */
	@ApiModelProperty(value = "结果数据", required = true)
	private Object data;

	public Integer getCode() {
		return code;
	}

	public void setCode(Integer code) {
		this.code = code;
	}

	public String getMessage() {
		return message;
	}

	public void setMessage(String message) {
		this.message = message;
	}

	public Object getData() {
		return data;
	}

	public void setData(Object data) {
		this.data = data;
	}

	public ResultVO(Integer code, String message, Object data) {
		super();
		this.code = code;
		this.message = message;
		this.data = data;
	}

	public ResultVO() {
		super();
		// TODO Auto-generated constructor stub
	}

	@Override
	public String toString() {

		return "ResultVO [code=" + code + ", message=" + message + ", data=" + data + "]";
	}
}

3.5 ALL注解代码示例说明，如下：

@Api(tags = "物料库存数量抓取接口说明")
@RestController
@CrossOrigin(origins = "*", maxAge = 5000)
@Slf4j
public class EbgStockController {

    @Autowired
    private EbgStockJcoConnService ebgStockJcoConnService;

    @Secret(BaseClass.class)
    @ApiOperation(value = "物料库存数量抓取", notes =  "通过传送{\"plant\":\"\",\"mlist\":[{\"sign\":\"\",\"option\":\"\",\"low\":\"\",\"high\":\"\"}]," +
            "\"slist\":[{\"sign\":\"\",\"option\":\"\",\"low\":\"\",\"high\":\"\"}]}参数的加密串，获取物料库存数量相关信息。" +
            "示例：{\"s\":\"+Aj5EFZFoX/LOhHQfMUV4Hp4/nbsiCsHW6D3SVxmfcjY4hk/UlFshpG3nsE0UVvtLryTgv/6/KyzRBjLlOiV2RVxkilQ90dBRhxPFkTg3znVCMfLSY/wu81OYXZeKsGO\"}")
    /*@ApiImplicitParams({
            @ApiImplicitParam(name = "s", value = "请求参数实体类明细", required = true, paramType = "body", dataType ="EbgStocksTVO")
    })*/
    @ApiResponses({
            @ApiResponse(code = 1, message = "接口调用成功返回的data数据明细", response = EbgStocksTPO.class)
    })
    @PostMapping("/getEbgStockInfo")
    public ResultVO getEbgStockInfoFromOracle(@RequestBody EbgStocksTVO ebgStocksTVO) {
        ResultVO rv = new ResultVO();
        if (!ObjectUtils.isEmpty(ebgStocksTVO)) {
            log.info("ebgStocksTBO:" + ebgStocksTVO);
            rv = this.ebgStockJcoConnService.getEbgStockInfoFromOracle(ebgStocksTVO);
            log.info("rv:" + rv);
        }
        return rv;
    }
}

四、knife4j 画面展示

4.1 主页面显示：

4.2 接口说明页面显示：