Java 5-22、Swagger Api在线文档与Knife4j

Java 5-22、Swagger Api在线文档与Knife4j 5-22 Swagger Api在线文档与Knife4j 简介

官网地址

Swagger是一个用于 生成、描述、调用 RESTful 接口的Web服务，
可以将项目中对外暴露的接口展现在Web页面上，并且可以进行接口的调用和调试，代替Postman

作用和好处：

跟随项目代码，编译时动态实时生成新的接口文档可以将指定的接口，展现在web文档页面可以直接进行接口调试，降低开发阶段成本

tips:

所有使用方法均为注解，且均已Apixxx开头所有注解只会存在于Controller层和Model层

配置

建议：不要使用最新版3.0.0+,会有兼容问题

一、依赖

遵循 OpenApi 规范的core库

    io.springfox
    springfox-swagger2
    2.9.2

Swagger UI库

    io.springfox
    springfox-swagger-ui
    2.9.2

版本兼容

swagger 2.9.2版本自带的models库，版本未1.5.20，该版本会有一个警告一直抛出在控制台，于是我们需要排除错误版本，引入 1.5.22版本来解决这个问题

java.lang.NumberFormatException: For input string: ""

最后展示一下最终依赖：

    io.springfox
    springfox-swagger2
    2.9.2
    
    
        
            io.swagger
            swagger-models
        
    




    io.swagger
    swagger-models
    1.5.22




    io.springfox
    springfox-swagger-ui
    2.9.2

二、启动项配置

package com.a2j.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.documentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2 // 开启Swagger web服务
public class SwaggerApiConfig {

    @Bean
    public Docket swagger() {
        return new Docket(documentationType.SWAGGER_2)
                .apiInfo(apiInfo()) // Api配置
                .groupName("a2j模块") // 分组名称
                .select() // 构建选择器builder配置
                .apis(RequestHandlerSelectors.basePackage("com.a2j.controller")) // 扫描接口的包路径
                .paths(PathSelectors.any()) // 扫描路径
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("A2J-Api接口文档")
                .description("接口描述、参数描述、字段描述、在线调试")
                .version("1.0.0")
                .contact(new Contact("bzb", "", ""))
                .build();
    }
}

此时使用 http://localhost:1234/swagger-ui.html 访问就能看到文档了！

使用 一、类注解

@Api

作用于`Controller`层的接口类，描述接口信息
常用参数： `tags`

属性名类型描述tagsString[]类的说明valueStringurl路径hiddenBoolean在文档中隐藏显示

---

@ApiModel

作用于`Model`层的实体类VO对象，描述对象信息
配合 `@ApiImplicitParams` 和 `@RequestBody`使用
常用参数：`description`

属性名类型描述descriptionString类的说明valueString对象名parentClass继承父级类的.class 二、方法注解

@ApiOperation

作用于`Controller`层的接口方法上，描述接口信息
常用参数：`value`、`notes`

value 该接口作用说明，直接UI呈现notes 备注，适合接口的详细描述response 返回值类型的.class

---

@ApiImplicitParam
@ApiImplicitParams

作用于`Controller`层的接口方法上，描述入参数据信息
`@ApiImplicitParam`  用于参数类型为`基础数据`的时候
`@ApiImplicitParams` 用于参数类型为`实体类对象`类型的时候
常用参数：`value`、`notes`

name 参数名

value 参数说明

required 是否为必传参数，默认false

paramType 入参方式，header/query/path/body

dataType 参数类型，默认String，int/String

defaultValue 参数默认值

---

@ApiResponse
@ApiResponses

作用于`Controller`层的接口方法上，描述出参数据信息。此功能最后有全局处理的方式优化。
`@ApiResponse`  用于描述单个响应码
`@ApiResponses` 用于描述多个响应码
常用参数：`code`、`message`

code 响应码

message 响应码的对应说明

response 可能抛出异常的数据类型的.class

三、属性字段注解

@ApiModelProperty

作用于`Model`层的属性上，描述字段信息
常用参数：`value`	

value 属性说明

required 是否必传，默认true

example 默认值

hidden 隐藏显示，默认false

使用案例：

package com.a2j.controller.car;

import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
...


@RestController
@RequestMapping("/carType")
@Api(tags = "车型接口")
public class CarTypeController {

    @Autowired
    CarTypeService service;

    
    @PostMapping("/addCarType")
    @ApiOperation(value = "新增车型")
    @ApiImplicitParams({})
    @ApiResponse(code = 200, message = "请求成功")
    public baseBean addCarType(@RequestBody CarTypeVO record) {
        service.addCarType(record);
        return baseBean.success(ResponseCode.SUCCESS);
    }

    
    @PutMapping("/delCarType/{id}")
    @ApiOperation(value = "删除车型")
    @ApiImplicitParam(name = "id", value = "车型id", required = true, dataType = "int", paramType = "path", defaultValue = "100")
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),    
            @ApiResponse(code = 404, message = "接口不存在")    
    })
    public baseBean delCarType(@PathVariable Integer id) {
        service.delCarType(id);
        return baseBean.success(ResponseCode.SUCCESS);
    }
}




package com.a2j.beans.car.type;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;


@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "车型出入参对象")
public class CarTypeVO {

    @ApiModelProperty(value = "品牌id", hidden = true)
    private Integer brandId;

    @ApiModelProperty(value = "车系名称", required = true, example = "迈凯伦")
    private String typeName;

    ...
}

ApiResponse优化

上面我们介绍了 @ApiResponse 的使用方法
对于接口返回描述，每个接口都去加上同样的内容过于繁琐，于是我们使用全局的响应码配置处理。

@Bean
public Docket swagger() {
    // 全局响应码统一处理
    List responseMessages = new ArrayList<>();
    for (ResponseCode value : ResponseCode.values()) {
        // 大于1000的不对外显示
        if (value.getCode() > 1000) continue;
        responseMessages.add(
                new ResponseMessageBuilder()
                        .code(value.getCode())
                        .message(value.getMessage())
                        .build()
        );
    }

    return new Docket(documentationType.SWAGGER_2)
            .useDefaultResponseMessages(false) // 不使用默认的响应码描述
            .globalResponseMessage(RequestMethod.GET, responseMessages)
            .globalResponseMessage(RequestMethod.POST, responseMessages)
            .globalResponseMessage(RequestMethod.PUT, responseMessages)
            .globalResponseMessage(RequestMethod.DELETE, responseMessages);
}

Knife4j优化Swagger

Knife4j是Swagger的UI增强版，
Swagger现有的体验有如下缺陷，所以我们需要升级增强版 Knife4j

1. 文档界面粗糙，不易 *** 作
   入参对象属性过多时阅读性差，在线调试不够友好

2. 正式环境无法关闭文档
   Swagger有解决方案，但不是自有配置

一、在pom.xml中改造依赖如下：

第一层级


    
        
            com.github.xiaoymin
            knife4j-dependencies
            2.0.8
            pom
            import
        
    



第二层级

    
    
        com.github.xiaoymin
        knife4j-spring-boot-starter
    

    
    
        io.springfox
        springfox-swagger-ui
    

二、对启动配置项修改

@EnableSwagger2 修改为：@EnableSwagger2WebMvc

原来的：

import springfox.documentation.swagger2.annotations.EnableSwagger2;

// http://localhost:1234/swagger-ui.html
@Configuration
@EnableSwagger2 // 开启Swagger web服务
public class SwaggerApiConfig {

}


现在的：

import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

// http://localhost:1234/doc.html
@Configuration
@EnableSwagger2WebMvc // 开启Swagger web服务
public class SwaggerApiConfig {

}

application-dev.yml增加配置

# knife4j
knife4j:
  enable: true # 开启增强模式,下面高级设置才生效
  production: false # 是否为生产环境
  basic:
    enable: true # 开启knife4j
    username: bzb
    password: 123

application-prod.yml增加配置

# knife4j
knife4j:
  enable: true # 开启增强模式,下面高级设置才生效
  production: true # 是否为生产环境
  basic:
    enable: true # 开启knife4j
    username: bzb
    password: 123

至此，配置就结束了，此时文档的访问地址为 http://localhost:1234/doc.html ，快去看看惊艳到你了没吧！