SpringBoot-Swagger-Knife4j

创建工程

  • 基于初始化器创建SpringBoot 项目

  • 添加如下依赖

    1
    2
    3
    4
    5
    6
    7
    		 
    <!-- springboot 2.7.9 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.9</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    		 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    		 
    <!-- lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>

    <!--  swagger https://doc.xiaominfo.com/v2/documentation/ -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
        <version>4.0.0</version>
    </dependency>

  • 目录基本结构

    项目结构

创建配置

  • 基于YML 文件创建 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    		 
    # SpringBoot 启动端口
    server:
      port: 9800

    knife4j:
      enable: true
      openapi:
        title: 智慧校园云台系统接口文档
        description: "`智慧校园云台系统接口文档`
        # aaa"
        email: 3327511395@qq.com
        concat: coder-itl
        url: https://docs.xiaominfo.com
        version: v4.0
        license: Apache 2.0
        license-url: https://stackoverflow.com/
        terms-of-service-url: https://stackoverflow.com/
        group:
          test1:
            group-name: 分组名称
            api-rule: package
            api-rule-resources:
              - com.example.zhxy.controller

    • 显示效果

      渲染效果

  • 基于配置类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    		 
    // 选其一
    package com.example.zhxy.config;

    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.bind.annotation.RestController;
    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.EnableSwagger2WebMvc;

    import java.util.ArrayList;

    @Configuration
    @EnableSwagger2WebMvc
    public class Knife4jConfiguration {
        @Bean
        public ApiInfo apiInfo() {
            Contact contact = new Contact("coder-itl", "https://coder-itl.github.io", "coderitl@gmail.com");
            return new ApiInfo(
                    "智慧校园", // 标题
                    "API-后台文档",// 描述
                    "v1.0",// 文档版本信息
                    "https://coder-itl.github.io", // 组织链接
                    contact,// 联系人
                    "Apache 2.0", // 许可
                    "https://coder-itl.github.io", // 许可链接
                    new ArrayList<>() // 扩展
            );
        }

        @Bean
        public Docket dockerBean(ApiInfo apiInfo) {
            //指定使用Swagger2规范
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                    // 通过 .select() 方法配置扫描接口
                    .select()
                    // 这里指定Controller扫描包路径
                    .apis(RequestHandlerSelectors.basePackage("com.example.zhxy.controller"))
                    // 也可以使用 withClassAnnotation,仅仅扫描带有 RestController 注解的类
                    // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    .build();
            return docket;
        }
    }

Swagger-常用注解

  • 注解解释

    注解 说明
    @Api(tags="xxx模块说明,出现在控制器类上") 作用在模块(控制器类) 类上
    @ApiParam(xxx参数说明) 作用在参数、方法和字段上，required 为true 表示必须传参数
    @ApiModel(xxx Pojo说明) 作用在实体类上
    @ApiOperation(xxx接口说明) 作用在接口方法上
    @ApiModelProperty(value=xxx属性说明),hidden=true 作用在类方法·和属性上,hidden 为true 可以隐藏该属性,required 为true 表示添加或修改数据时为必填参数

  • 控制器使用

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    		 
    @Api(tags = "测试")
    @RestController
    public class HelloController {
        @ApiOperation("显示用户信息")
        @GetMapping(value = "/user")
        public User getUser() {
            return new User("coder-itl", "211321059", "coder-itl", "123456");
        }

        @ApiOperation("参数拼接")
        @PostMapping("/param")
        public String hello2(@ApiParam("用户名") String name) {
            return "hello" + name;
        }
    }
    显示用户信息 参数拼接

  • 实体类使用

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    		 
    @Data
    @ApiModel("用户实体")
    @NoArgsConstructor
    @AllArgsConstructor
    public class User {
        @ApiModelProperty(value = "用户名",required = true)
        private String username;
        @ApiModelProperty(value = "学号/教师ID",required = true)
        private String userId;
        // TODO: hidden=true
        @ApiModelProperty(value = "密码",required = true)
        private String passwd;
        @ApiModelProperty(value = "手机号",required = true)
        private String phone;
    }
    用户实体

  • 启动，访问路径, 端口为SpringBoot项目自定义端口

    http://localhost:9800/doc.html

分组配置

  • 配置类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    		 
    package com.example.zhxy.config;

    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.data.util.Predicates;
    import org.springframework.web.bind.annotation.RestController;
    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.EnableSwagger2WebMvc;

    import java.util.ArrayList;

    @Configuration
    @EnableSwagger2WebMvc
    public class Knife4jConfiguration {
        @Bean
        public Docket adminApiConfig(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("adminApi")
                    .apiInfo(adminApiInfo())
                    .select()
                    .paths(PathSelectors.regex("/admin/.*"))
                    .build();
        }
        @Bean
        public Docket webApiConfig(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    .paths(PathSelectors.regex("/api/.*"))
                    .build();
        }


        private ApiInfo adminApiInfo(){
            return new ApiInfoBuilder()
                    .title("后台管理系统API文档")
                    .description("本文档描述了后台管理系统的各个模块的接口的调用方式")
                    .version("1.6")
                    .contact(new Contact("", "", ""))
                    .build();
        }

        private ApiInfo webApiInfo(){
            return new ApiInfoBuilder()
                    .title("网站API文档")
                    .description("本文档描述了网站各个模块的接口的调用方式")
                    .version("1.6")
                    .contact(new Contact("", "", ""))
                    .build();
        }
    }

  • 控制器修改

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    		 
    package com.example.zhxy.controller;

    import com.example.zhxy.domain.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RestController;

    @Api(tags = "测试")
    @RestController
    public class HelloController {
        @ApiOperation("显示用户信息")
        @GetMapping(value = "/admin/user/u1")
        public User getUser1() {
            return new User("coder-itl", "211321059", "coder-itl", "123456");
        }

        @ApiOperation("显示用户信息")
        @GetMapping(value = "/admin/user/u2")
        public User getUser3() {
            return new User("coder-itl", "211321059", "coder-itl", "123456");
        }


        @ApiOperation("显示用户信息")
        @GetMapping(value = "/api/user")
        public User getUser2() {
            return new User("coder-itl", "211321059", "coder-itl", "123456");
        }
        @ApiOperation("参数拼接")
        @PostMapping("/param")
        public String hello2(@ApiParam("用户名") String name) {
            return "hello" + name;
        }
    }

  • 效果

    webApi,拦截以/api/* 所有请求 adminApi,拦截以/admin/* 所有请求