快速开始

本章节将指导您如何在 Spring Boot 项目中集成并使用 SpringDoc。

版本支持

SpringDoc 支持不同版本的 Spring Boot，请根据您的项目选择合适的版本：

• SpringBoot 2.x 版本：请使用 1.0.3
• SpringBoot 3.x 版本：请使用 2.0.1（感谢 zhangslq 贡献支持 Boot3 版本的代码）

安装依赖

根据您的 Spring Boot 版本选择合适的 SpringDoc 版本：

SpringBoot 2.x 版本

Maven

<dependency>
    <groupId>io.github.lvcongzheng520</groupId>
    <artifactId>springdoc</artifactId>
    <version>1.0.3</version>
</dependency>

Gradle

implementation group: 'io.github.lvcongzheng520', name: 'springdoc', version: '1.0.3'

SpringBoot 3.x 版本

Maven

<dependency>
    <groupId>io.github.lvcongzheng520</groupId>
    <artifactId>springdoc</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle

implementation group: 'io.github.lvcongzheng520', name: 'springdoc', version: '2.0.1'

JavaDoc 插件配置

由于 SpringDoc 基于 JavaDoc 工作，您需要配置 JavaDoc 注解处理器。这是 SpringDoc 正常工作的关键配置。

重要提示

JavaDoc 插件配置是必需的，没有此配置 SpringDoc 将无法正常工作。

在 Maven 项目中，添加以下插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.9.0</version>
            <configuration>
                <source>${java.version}</source>
                <target>${java.version}</target>
                <encoding>${project.build.sourceEncoding}</encoding>
                <annotationProcessorPaths>
                    <!-- SpringDoc 核心注解处理器 -->
                    <path>
                        <groupId>com.github.therapi</groupId>
                        <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                        <version>0.15.0</version>
                    </path>
                    <!-- 如果使用 Lombok，需要添加此依赖 -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <!-- Spring Boot 配置处理器 -->
                    <path>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-configuration-processor</artifactId>
                        <version>${springboot.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

配置说明

• therapi-runtime-javadoc-scribe：SpringDoc 的核心注解处理器，用于解析 JavaDoc 注释
• lombok：如果项目中使用 Lombok，需要添加此依赖以避免冲突
• spring-boot-configuration-processor：Spring Boot 配置处理器，用于处理配置属性

添加应用配置

在 application.properties 或 application.yml 中添加 SpringDoc 配置：

重要提示

packages-to-scan 配置项需要根据您的项目包结构进行修改，请将 com.example 替换为您实际的包名。

application.yml

# SpringDoc OpenAPI 配置
springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
    # OpenAPI文档的路径
    path: /v3/api-docs
  swagger-ui:
    # swagger-ui路径
    path: /swagger-ui.html
    # 持久化认证数据
    persistAuthorization: true
  info:
    # 标题
    title: '标题：SpringDoc后台管理系统_接口文档'
    # 描述
    description: '描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...'
    # 版本
    version: '版本号: 1.0.0'
    # 作者信息
    contact:
      name: lcz
      email: 1926585708@qq.com
      url: https://gitee.com/hsqyz
  components:
    # 鉴权方式配置
    security-schemes:
      apiKey:
        type: APIKEY
        in: HEADER
        name: Authorization
  # 分组配置
  group-configs:
    - group: SpringDoc项目模块接口文档
      packages-to-scan: com.hsqyz

application.properties

# SpringDoc OpenAPI 配置
# 是否开启接口文档
springdoc.api-docs.enabled=true
# OpenAPI文档的路径
springdoc.api-docs.path=/v3/api-docs
# swagger-ui路径
springdoc.swagger-ui.path=/swagger-ui.html
# 持久化认证数据
springdoc.swagger-ui.persistAuthorization=true
# 标题
springdoc.info.title=标题：SpringDoc后台管理系统_接口文档
# 描述
springdoc.info.description=描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...
# 版本
springdoc.info.version=版本号: 1.0.0
# 作者姓名
springdoc.info.contact.name=lcz
# 作者邮箱
springdoc.info.contact.email=1926585708@qq.com
# 作者网站
springdoc.info.contact.url=https://gitee.com/hsqyz
# 鉴权方式
springdoc.components.security-schemes.apiKey.type=APIKEY
springdoc.components.security-schemes.apiKey.in=HEADER
springdoc.components.security-schemes.apiKey.name=Authorization
# 分组名称
springdoc.group-configs[0].group=SpringDoc项目模块接口文档
# 扫描包路径
springdoc.group-configs[0].packages-to-scan=com.hsqyz

编写 API 文档

现在，您只需要在控制器和方法上添加标准的 JavaDoc 注释，SpringDoc 将自动生成 API 文档。

/**
 * 用户管理控制器
 * 提供用户的增删改查等功能
 */
@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    /**
     * 获取用户列表
     * 
     * @param page 页码，从0开始
     * @param size 每页数量
     * @return 用户列表
     */
    @GetMapping
    public Page<User> getUsers(@RequestParam(defaultValue = "0") int page, 
                               @RequestParam(defaultValue = "10") int size) {
        return userService.getUsers(page, size);
    }

    /**
     * 根据ID获取用户
     * 
     * @param id 用户ID
     * @return 用户信息
     */
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.getUser(id);
    }

    /**
     * 创建新用户
     * 
     * @param user 用户信息
     * @return 创建的用户
     */
    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}

访问文档

启动 Spring Boot 应用后，您可以通过以下 URL 访问 API 文档：

• Knife4j 文档界面: http://localhost:8080/swagger-ui.html
• OpenAPI 规范文档: http://localhost:8080/v3/api-docs

下一步

详细了解 SpringDoc 的配置选项，以满足不同的项目需求。