快速开始

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

安装依赖

首先，需要在您的项目中添加 SpringDoc 依赖。

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'

JavaDoc 插件配置

由于 SpringDoc 基于 JavaDoc 工作，您需要配置 JavaDoc 注解处理器。在 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>
                    <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>

添加应用配置

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

application.yml

# springdoc-openai 配置
springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
    # OpenAPI文档的路径
    path: /v3/api-docs
  swagger-ui:
    # swagger-ui路径
    path: /swagger-ui.html
    # 持久化认证数据
    persistAuthorization: true
  info:
    # 标题
    title: 'SpringDoc API 文档'
    # 描述
    description: '项目 API 文档说明'
    # 版本
    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: 默认接口文档
      packages-to-scan: com.example

application.properties

# springdoc-openai 配置
# 是否开启接口文档
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 API 文档
# 描述
springdoc.info.description=项目 API 文档说明
# 版本
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.group-configs[0].packages-to-scan=com.example

编写 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 的配置选项，以满足不同的项目需求。