springboot集成swagger、knife4j

1. 集成swagger2

1.1 引入依赖

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

1.2 添加Swagger配置

关键 RequestHandlerSelectors.basePackage(“com.gz”)

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                // 要扫描的API(Controller)基础包
                .apis(RequestHandlerSelectors.basePackage("com.gz"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo() {
        Contact contact = new Contact("gz","","");
        return new ApiInfoBuilder()
                .title("测试swagger-springbootdemo API文档")
                .description("springbootdemo后台api")
                .contact(contact)
                .version("1.0.0").build();
    }
}

通常情况下，swagger配置放在common模块中，别的模块需要集成swagger时，只需要引入common模块就行，因此需要将SwaggerConfiguration类在META-INF/spring.facories文件里进行配置，这样才能将SwaggerConfiguration类注册进IOC容器。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.gzdemo.springbootdemo.config.SwaggerConfiguration

但是如果SwaggerConfiguration类在启动类的同级目录或子目录下，就不需要此项配置了。

1.3 controllers和models

TestController

@RequestMapping("/test")
@RestController
public class TestController {
    
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
    
    @PostMapping("/addUser")
    public Map addUser(@RequestBody UserDto userDto){
        Map<String, Object> result = new HashMap<>();
        UserDto userDto1 = new UserDto();
        userDto1.setName("ceshi");
        userDto1.setAge(23);
        userDto1.setPhone("15700000001");
        userDto1.setEmail("111@qq.com");
        result.put("data",userDto1);
        result.put("msg","添加成功");
        return result;
    }
}

UserDto

@Data
public class UserDto {
    private String name;
    private String phone;
    private Integer age;
    private String email;
}

1.4 浏览器访问

浏览器访问 http://localhost:8080/swagger-ui.html

2. Swagger常用注解

2.1 Swagger常用注解

在Java类中添加Swagger的注解即可生成Swagger接口文档，常用Swagger注解如下：

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

2.2 测试

我们在TestController和UserDto中添加Swagger注解，代码如下所示：

@RequestMapping("/test")
@RestController
@Api(value = "测试控制器",tags = "test")
public class TestController {

    @ApiOperation("用户测试hello")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @ApiOperation("添加用户")
    @PostMapping("/addUser")
    public Map addUser(@RequestBody UserDto userDto){
        Map<String, Object> result = new HashMap<>();
        UserDto userDto1 = new UserDto();
        userDto1.setName("ceshi");
        userDto1.setAge(23);
        userDto1.setPhone("15700000001");
        userDto1.setEmail("111@qq.com");
        result.put("data",userDto1);
        result.put("msg","添加成功");
        return result;
    }
}

@Data
public class UserDto {

    @ApiModelProperty(value="姓名",required = true)
    private String name;

    @ApiModelProperty(value="手机号",required = true)
    private String phone;

    @ApiModelProperty(value="年龄",required = true)
    private Integer age;

    @ApiModelProperty(value="邮箱",required = true)
    private String email;
}

启动应用，访问 http://localhost:8080/swagger-ui.html

3. 集成knife4j

1. 添加依赖

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

2. 添加注解

• 在SwaggerConfiguration类上添加 @EnableKnife4j
• 在SwaggerConfiguration类上添加@Import(BeanValidatorPluginsConfiguration.class)，可能会报错，可以不用加这个，也不知道加了有什么用

3. 浏览器访问

http://localhost:8080/doc.html