使用Swagger只需按照它的规范去定义接口以及接口相关信息，就可以做到生成接口文档，以及在线接口调试页面

预览效果

img1
img2

Knife4j是为Java Mvc 框架集成Swagger生成Api文档的增强解决方案。

配置

  1. 导入knife4j的maven坐标

    1
    2
    3
    4
    5
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
    	<version>3.0.2</version>
    </dependency>

  2. 配置类WebMvcConfiguration中加入knife4j的相关配置

    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
    /**
     * 配置类，注册web层相关组件
     */
    @Configuration
    @Slf4j
    public class WebMvcConfiguration extends WebMvcConfigurationSupport {
        /**
         * 通过knife4j生成接口文档
         * @return
         */
        @Bean
        public Docket docket() {
    		log.info("开始生成接口文档...");
            ApiInfo apiInfo = new ApiInfoBuilder()
                    .title("XXXX项目接口文档")
                    .version("2.0")//版本
                    .description("XXXX项目接口文档")//简介
                    .build();
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                    .select()
    				//指定生成接口需要扫描的包
                    .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))//
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }

        
    }

    当接口功能差不多，需要区分用户端接口和管理端接口时，只需添加关键词groupName("用户端接口")，多写一份docket即可

    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
    @Bean
    public Docket docket1() {
        log.info("开始生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    @Bean
    public Docket docket2() {
        log.info("开始生成接口文档...");
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

  3. 在配置类WebMvcConfiguration设置静态资源映射，否则接口文档页面无法访问

    1
    2
    3
    4
    5
    6
    7
    8
    9
    /**
    * 设置静态资源映射
    * @param registry
    */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    	log.info("开始设置静态资源映射...");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

启动项目，可以看到控制台输出日志：开始生成接口文档…和开始设置静态资源映射…,访问localhost:8080/doc.html即可看到

常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解 说明
@Api 用在类上，例如Controller，表示对类的说明，例:@Api(tags="员工相关接口")
@ApiModel 用在类上，例如entity、DTO、VO,例：@ApiModel(description = "员工登录时传递的数据模型")
@ApiModelProperty 用在属性上，描述属性信息,例:@ApiModelProperty("用户名")
@ApiOperation 用在方法上，例如Controller的方法，说明方法的用途、作用,例:@ApiOperation(value="员工登录")

注解应用示例

@Api

1
2
@Api(tags="员工相关接口")
public class EmployeeController

@ApiOperation

1
2
@ApiOperation(value="员工退出")
public Result<String> logout()

@ApiModel,@ApiModelProperty

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@ApiModel(description = "员工登录返回的数据格式")
public class EmployeeLoginVO implements Serializable {

    @ApiModelProperty("主键值")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("jwt令牌")
    private String token;

}

SpringBoot3使用Swagger3

  1. 引入依赖和阿里云镜像

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    <dependencies>
         <!--swagger3-->
         <dependency>
             <groupId>com.github.xiaoymin</groupId>
             <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
             <version>4.3.0</version>
         </dependency>
     </dependencies>

     <repositories>
         <!--阿里云镜像-->
         <repository>
             <id>alimaven</id>
             <name>aliyun maven</name>
             <url>https://maven.aliyun.com/nexus/content/groups/public/</url>
             <releases>
                 <enabled>true</enabled>
             </releases>
             <snapshots>
                 <enabled>true</enabled>
             </snapshots>
         </repository>
     </repositories>

  2. 启动项目访问：