springboot集成springdoc

SpringDoc 是一个基于 OpenAPI 3.0 规范的开源 API 文档生成工具，专为 Spring Boot 应用设计。它能自动扫描项目中的 REST 接口，生成标准化的 API 文档。

springdoc-openapi v1

由于springdoc v1和v2对应支持不同的springboot版本，所以我们拆分为两个部分做示例。

支持的springboot版本

Spring-boot (v1, v2 and v3)

maven引入

主要

springdoc-openapi-ui自带swagger界面，项目启动后路径：/swagger-ui.html

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

无UI界面

如果你只需要生成接口文档而不需要swagger界面，则引入核心依赖即可,接口文档路径：/v3/api-docs

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webmvc-core</artifactId>
    <version>1.8.0</version>
</dependency>

JavaDoc支持

javadoc可以读取代码中的注释生成文档，不需要使用额外注解

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-javadoc</artifactId>
    <version>1.8.0</version>
</dependency>

注意：引入maven依赖后还需要添加maven插件才能生效

<build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>0.15.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
</build>

注意！！如果项目中使用到了Lombok，则还需要同时引入lombok插件，否则会导致lombok不生效

<build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven-compiler-plugin.version}</version>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>${therapi-runtime-javadoc.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>

完整项目依赖

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>demo</description>

    <properties>
        <java.version>17</java.version>
        <springdoc.version>1.8.0</springdoc.version>
        <spring-boot.version>2.7.18</spring-boot.version>
        <therapi-runtime-javadoc.version>0.15.0</therapi-runtime-javadoc.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!--springboot固定依赖pom-->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <dependency>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-ui</artifactId>
                <version>${springdoc.version}</version>
            </dependency>

            <dependency>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-javadoc</artifactId>
                <version>${springdoc.version}</version>
            </dependency>

        </dependencies>
    </dependencyManagement>

    <dependencies>

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-javadoc</artifactId>
        </dependency>


        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

    </dependencies>

    <!--必须要有maven插件 否则报错-->
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>${therapi-runtime-javadoc.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <skip>false</skip>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

测试接口

/**
 * springboot集成springdoc测试模块
 */
@RestController
public class TestController {

    /**
     * 查询服务器当前时间
     * @return 服务器当前时间字符串 格式：yyyy-MM-dd hh:mm:ss
     */
    @GetMapping("/queryDate")
    public String queryDate(){
        // 创建时间格式器
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

        // 获取当前时间并格式化
        return LocalDateTime.now().format(formatter);
    }
}

springdoc-openapi v2

支持的springboot版本

Spring-boot v3 (Java 17 & Jakarta EE 9)

maven引入

主要

自带swagger界面，项目启动后路径：/swagger-ui.html

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.14</version>
</dependency>

无UI界面

项目启动后路径：/v3/api-docs

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.8.14</version>
</dependency>

Scalar UI 界面支持

Scalar 是一个开源 API 平台，旨在创建美观、交互式的 API 文档，并内置 REST API 客户端，并对 OpenAPI（前身为 Swagger）规范提供一流的支持它特别旨在提升开发者在探索 API 时的体验。

项目启动后路径：/scalar

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-scalar</artifactId>
    <version>2.8.14</version>
</dependency>

JavaDoc支持

<dependency>
    <groupId>com.github.therapi</groupId>
    <artifactId>therapi-runtime-javadoc</artifactId>
    <version>0.15.0</version>
</dependency>

注意：引入maven依赖后还需要添加maven插件才能生效

<build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>0.15.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
</build>

注意！！如果项目中使用到了Lombok，则还需要同时引入lombok插件，否则会导致lombok不生效

<build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven-compiler-plugin.version}</version>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>${therapi-runtime-javadoc.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>

完整项目依赖

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>demo2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo2</name>
    <description>demo2</description>

    <properties>
        <java.version>17</java.version>
        <springdoc.version>2.8.14</springdoc.version>
        <spring-boot.version>3.5.8</spring-boot.version>
        <therapi-runtime-javadoc.version>0.15.0</therapi-runtime-javadoc.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!--springboot固定依赖pom-->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <dependency>
                <groupId>org.springdoc</groupId>
                <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
                <version>${springdoc.version}</version>
            </dependency>

            <dependency>
                <groupId>com.github.therapi</groupId>
                <artifactId>therapi-runtime-javadoc</artifactId>
                <version>${therapi-runtime-javadoc.version}</version>
            </dependency>

        </dependencies>
    </dependencyManagement>

    <dependencies>

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        </dependency>

        <dependency>
            <groupId>com.github.therapi</groupId>
            <artifactId>therapi-runtime-javadoc</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

    </dependencies>

    <!--必须要有maven插件 否则报错-->
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>com.github.therapi</groupId>
                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                            <version>${therapi-runtime-javadoc.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <skip>false</skip>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

测试接口

/**
 * springboot集成springdoc测试模块
 */
@RestController
public class TestController {

    /**
     * 查询服务器当前时间
     * @return 服务器当前时间字符串 格式：yyyy-MM-dd hh:mm:ss
     */
    @GetMapping("/queryDate")
    public String queryDate(){
        // 创建时间格式器
        DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

        // 获取当前时间并格式化
        return LocalDateTime.now().format(formatter);
    }
}

依赖排除

我们在生产环境中并不需要使用到springdoc，所以我们可以将相关依赖全部排除，上线打包中只有项目相关的源码没有文档，我们在pom.xml中加入<profile>用于指定排除生产环境的依赖，生产打包时使用-P指定环境id即可：mvn clean package -P prod-env

<!-- 2. 配置 Profile，生产环境排除 springdoc -->
    <profiles>
        <!-- 测试环境（默认激活，保留 springdoc） -->
        <profile>
            <id>test-env</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
        </profile>

        <!-- 生产环境（激活时排除 springdoc） -->
        <profile>
            <id>prod-env</id>
            <activation>
                <activeByDefault>false</activeByDefault>
            </activation>
            <dependencies>
                <!-- 若 springdoc 直接全局引入，需单独排除 -->
                <dependency>
                    <groupId>org.springdoc</groupId>
                    <artifactId>springdoc-openapi-ui</artifactId>
                    <!-- 生产环境不打包 -->
                    <scope>provided</scope>
                </dependency>

                <dependency>
                    <groupId>org.springdoc</groupId>
                    <artifactId>springdoc-openapi-webmvc-core</artifactId>
                    <scope>provided</scope>
                </dependency>

                <dependency>
                    <groupId>org.springdoc</groupId>
                    <artifactId>springdoc-openapi-javadoc</artifactId>
                    <scope>provided</scope>
                </dependency>
            </dependencies>

            <!--重写maven-compiler-plugin依赖 去除therapi-runtime-javadoc-scribe生成的文档-->
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <version>${maven-compiler-plugin.version}</version>
                        <configuration>
                            <annotationProcessorPaths>
                                <path>
                                    <groupId>org.projectlombok</groupId>
                                    <artifactId>lombok</artifactId>
                                    <version>${lombok.version}</version>
                                </path>
                            </annotationProcessorPaths>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>