SpringBoot配置swagger2-CSDN博客

本文链接：https://blog.csdn.net/weixin_52885473/article/details/141996109

一、前言

（查看具体操作步骤可跳过这一章节）

Swagger对于Spring Boot项目的重要性主要体现在以下几个方面：

1. 自动化API文档生成

节省时间和人力：Swagger能够自动从Spring Boot项目中提取注解信息，生成完整的API文档。这大大节省了开发人员手动编写和维护API文档的时间和精力。
实时同步：当Spring Boot项目的接口发生变化时，Swagger能够实时更新API文档，确保文档与项目实际情况的一致性。

2. 提高API的可读性和可访问性

交互式文档：Swagger生成的API文档是交互式的，开发者可以直接在文档页面上进行API的调用和测试，而无需编写额外的测试代码。
清晰的结构：Swagger文档以清晰的结构展示API的接口、参数、返回值等信息，使得API的使用者能够快速理解API的功能和使用方法。

3. 促进前后端分离开发

减少沟通成本：在前后端分离的开发模式下，Swagger作为中间桥梁，使得前端开发者能够直接通过Swagger文档了解后端API的详细信息，减少了前后端之间的沟通成本。
提高开发效率：前端开发者可以根据Swagger文档直接进行API的调用和测试，而无需等待后端接口的开发完成，从而提高了整个项目的开发效率。

4. 支持多种编程语言和框架

广泛的支持：Swagger不仅支持Spring Boot项目，还支持多种编程语言和框架，如Java、Python、PHP、JavaScript等。这使得Swagger能够在不同的项目中发挥重要作用。

5. 集成和部署方便

易于集成：Swagger可以与Spring Boot项目无缝集成，只需要添加相应的依赖和配置即可。
部署简单：Swagger生成的API文档可以直接通过Web服务器进行访问，无需额外的部署步骤。

综上所述，Swagger对于Spring Boot项目的重要性在于它能够提高API文档的自动化生成能力、增强API的可读性和可访问性、促进前后端分离开发、支持多种编程语言和框架以及方便集成和部署。这些优势使得Swagger成为Spring Boot项目中不可或缺的API文档和测试工具。

二、环境

java 1.8, maven 3.6.3, spring-boot 2.3.12.RELEASE；

1、单模块项目

一个模块内配置swagger，只有一个启动类；

2、多模块项目

swagger单独放在一个没有启动类的模块，其他模块要使用swagger时加入这个模块依赖；

三、配置方式

1、单模块项目

①pom.xml文件中加入swagger依赖，如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <groupId>com.jianji</groupId>
    <artifactId>backend</artifactId>
    <packaging>pom</packaging>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <swagger>2.9.2</swagger>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger}</version>
        </dependency>
    </dependencies>
</project>

②新建SwaggerConfig类

 
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，才生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，才生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("io.renren.controller"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(security());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("接口文档")
            .description("swagger接口文档")
            .version("3.0.0")
            .build();
    }
 
    private List<ApiKey> security() {
        return newArrayList(
            new ApiKey("token", "token", "header")
        );
    }
 
}

③直接运行项目即可在http://localhost:8080/swagger-ui.html#/访问到swagger-ui页面（8080为项目端口，可以改成你自己的项目端口）

2、多模块项目

①在你想放置swagger配置的模块中的pom.xml文件中引入swagger依赖，我的swagger模块为<common-swagger>如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>common</artifactId>
        <groupId>com.jianji</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>common-swagger</artifactId>

    <dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger}</version>
        </dependency>
    </dependencies>
</project>

②在common-swagger模块中，新建SwaggerConfig类：

 
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，才生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，才生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("io.renren.controller"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(security());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("接口文档")
            .description("swagger接口文档")
            .version("3.0.0")
            .build();
    }
 
    private List<ApiKey> security() {
        return newArrayList(
            new ApiKey("token", "token", "header")
        );
    }
 
}

③在需要添加swagger配置的模块的启动类中添加@EnableSwagger2，并在该模块的pom.xml文件中引入swagger配置模块common-swagger：

@EnableSwagger2

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@EnableSwagger2
@SpringBootApplication
public class MainApplication {
    public static void main(String[] args) {
        SpringApplication.run(MainApplication.class, args);
    }
}

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <artifactId>backend</artifactId>
        <groupId>com.jianji</groupId>
        <version>1.0-SNAPSHOT</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>main</artifactId>

    <dependencies>
        <dependency>
            <groupId>com.jianji</groupId>
            <artifactId>common-core</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>com.jianji</groupId>
            <artifactId>common-swagger</artifactId>
            <version>1.0-SNAPSHOT</version>
        </dependency>
    </dependencies>
</project>

④ 直接运行项目即可在http://localhost:8080/swagger-ui.html#/访问到swagger-ui页面（8080为项目端口，可以改成你自己的项目端口）