Swagger2与Springdoc集成与使用详解_Java

以下是将 swagger2 迁移到 springdoc（支持 openapi 3）的集成与使用指南，涵盖关键步骤、配置示例及注意事项：

1. 依赖配置

springdoc 是支持 openapi 3 规范的现代工具，适用于 spring boot 项目。

需替换或添加以下依赖：

<!-- maven 依赖 -->
<dependency>
    <groupid>org.springdoc</groupid>
    <artifactid>springdoc-openapi-starter-webmvc-ui</artifactid>
    <version>2.2.0</version> <!-- 使用最新版本 -->
</dependency>

注意：若项目原使用 springfox-swagger2，需移除相关依赖以避免冲突。

2. 基础配置

2.1 启用 springdoc

springdoc 自动配置，无需显式启用注解。

在 application.properties 或 application.yml 中配置基本信息：

# application.properties
springdoc.swagger-ui.enabled=true
springdoc.api-docs.path=/api-docs
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.version=1.0.0
springdoc.default-produces-media-type=application/json

2.2 自定义 openapi 信息

通过 java 配置类定义 api 元数据：

import io.swagger.v3.oas.models.openapi;
import io.swagger.v3.oas.models.info.info;

@configuration
public class openapiconfig {

    @bean
    public openapi customopenapi() {
        return new openapi()
                .info(new info()
                        .title("api 文档")
                        .version("1.0")
                        .description("基于 springdoc 的 openapi 文档")
                        .contact(new contact().name("开发者").email("dev@example.com"))
                        .license(new license().name("apache 2.0")));
    }
}

3. 注解使用

springdoc 使用 io.swagger.v3.oas.annotations 注解替代 io.swagger.annotations。

常用注解对照表：

swagger2 注解	springdoc 注解	用途
@api	@tag	控制器分类描述
@apioperation	@operation	接口方法描述
@apiparam	@parameter	方法参数描述
@apimodel	@schema	数据模型描述
@apimodelproperty	@schema	模型字段描述
@apiresponse	@apiresponse	接口响应描述

示例代码：

import io.swagger.v3.oas.annotations.operation;
import io.swagger.v3.oas.annotations.parameter;
import io.swagger.v3.oas.annotations.tags.tag;

@restcontroller
@tag(name = "用户管理", description = "用户相关操作接口")
@requestmapping("/users")
public class usercontroller {

    @operation(summary = "获取用户详情", description = "根据用户id查询详细信息")
    @getmapping("/{id}")
    public user getuser(
        @parameter(description = "用户id", required = true) @pathvariable long id) {
        // 业务逻辑
    }
}

4. 访问 swagger ui

启动应用后，通过以下 url 访问交互式文档界面：

swagger ui: http://localhost:8080/swagger-ui.html
openapi json: http://localhost:8080/v3/api-docs

5. 高级配置

5.1 分组多套 api

为不同模块配置多组 api 文档：

@bean
public groupedopenapi publicapi() {
    return groupedopenapi.builder()
            .group("public-apis")
            .pathstomatch("/api/public/**")
            .build();
}

@bean
public groupedopenapi adminapi() {
    return groupedopenapi.builder()
            .group("admin-apis")
            .pathstomatch("/api/admin/**")
            .build();
}

5.2 安全配置

集成 jwt 或 oauth2 时，添加安全方案：

@bean
public openapi customopenapi() {
    return new openapi()
            .components(new components()
                    .addsecurityschemes("bearerauth", 
                        new securityscheme()
                            .type(securityscheme.type.http)
                            .scheme("bearer")
                            .bearerformat("jwt")))
            .info(/* 略 */);
}

6. 与 spring security 集成

确保 spring security 允许访问文档端点：

@configuration
@enablewebsecurity
public class securityconfig {

    @bean
    public securityfilterchain filterchain(httpsecurity http) throws exception {
        http
            .authorizehttprequests(auth -> auth
                .requestmatchers("/swagger-ui/**", "/v3/api-docs/**").permitall()
                .anyrequest().authenticated()
            );
        return http.build();
    }
}