Swagger的快速配置与使用

一、pom文件引入

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<!--整合swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--整合Knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.8</version>
</dependency>

这里的swagger和Knife4j版本比较老了，用习惯这个页面了，就拿这个版本来举例子。

二、书写配置类SwaggerConfig

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
@Configuration
@EnableKnife4j
@EnableSwagger2
@ConditionalOnExpression("\${swagger.enable: true}")
class SwaggerConfig {

    @Bean
    fun createRestApi(): Docket? {
        return Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .useDefaultResponseMessages(false)
            .forCodeGeneration(false)
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(Api::class.java))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation::class.java) as Predicate<RequestHandler?>)
            .apis(RequestHandlerSelectors.basePackage("com.sucsoft.code"))
            .paths(PathSelectors.any())
            .build()
    }

    private fun apiInfo(): ApiInfo? {
        return ApiInfoBuilder()
            .title("项目接口文档")
            .description("AI许可证项目接口文档")
            .license("有问题问百度")
            .licenseUrl("https://www.baidu.com")
            .version("1.0")
            .build()
    }
}

1.注解解析

  • **@Configuration**声明这是一个Spring配置类，会被组件扫描自动识别。

  • **@EnableKnife4j**启用Knife4j（Swagger增强工具），提供更友好的UI界面和离线文档功能。

  • **@EnableSwagger2**启用Swagger2文档生成功能（这里在SpringFox 3.x+已改用@EnableOpenApi）。

  • **@ConditionalOnExpression**条件化配置，仅当配置文件中swagger.enable为true时生效（默认值为true）。

    在yml文件里配置

    1
    2
    3
    # application.yml
    swagger:
      enable: true # 生产环境可关闭

2.Docket Bean 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
@Bean
fun createRestApi(): Docket? {
    return Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())          // 设置文档基本信息
        .useDefaultResponseMessages(false) // 禁用默认响应消息（如400/404）
        .forCodeGeneration(false)    // 禁用代码生成相关配置
        .select()                    // 开始API选择器配置
        .apis(RequestHandlerSelectors.withClassAnnotation(Api::class.java))
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation::class.java) as Predicate<RequestHandler?>)
        .apis(RequestHandlerSelectors.basePackage("com.sucsoft.code")) // 指定扫描包
        .paths(PathSelectors.any())  // 扫描所有路径
        .build()
}

3.ApiInfo 文档信息

1
2
3
4
5
6
7
8
9
private fun apiInfo(): ApiInfo? {
    return ApiInfoBuilder()
        .title("项目接口文档")         // 文档标题
        .description("AI许可证项目接口文档") // 详细描述
        .license("有问题问百度")       // 许可证信息
        .licenseUrl("https://www.baidu.com") // 许可证URL
        .version("1.0")              // API版本
        .build()
}

如图
swagger