从Swagger 1（Wordnik）升级到Swagger 3：Spring XML配置替代方案咨询

核心替代逻辑 #

Wordnik是旧版Swagger（1.x/2.x）的实现，Swagger 3对应OpenAPI 3规范，Spring生态下主要通过SpringDoc OpenAPI集成，不再需要手动定义resourceWriter、apiWriter这类Bean，而是通过自动配置+自定义配置类实现相同功能。

具体Bean替代方案 #

1. swaggerConfig 替代 #

Wordnik的swaggerConfig负责配置API文档基础信息（标题、版本、描述等），在Swagger3中直接定义OpenAPI类型的Bean即可：
如果用Java配置类：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("你的API标题")
                        .version("1.0.0")
                        .description("API的详细描述")
                        .contact(new Contact().name("维护团队").email("xxx@example.com")))
                .addServersItem(new Server().url("/api").description("默认服务器地址"));
    }
}

如果保留Spring XML配置：

<bean id="customOpenAPI" class="io.swagger.v3.oas.models.OpenAPI">
    <property name="info">
        <bean class="io.swagger.v3.oas.models.info.Info">
            <property name="title" value="你的API标题"/>
            <property name="version" value="1.0.0"/>
            <property name="description" value="API的详细描述"/>
            <property name="contact">
                <bean class="io.swagger.v3.oas.models.info.Contact">
                    <property name="name" value="维护团队"/>
                    <property name="email" value="xxx@example.com"/>
                </bean>
            </property>
        </bean>
    </property>
    <property name="servers">
        <list>
            <bean class="io.swagger.v3.oas.models.servers.Server">
                <property name="url" value="/api"/>
                <property name="description" value="默认服务器地址"/>
            </bean>
        </list>
    </property>
</bean>

2. resourceWriter & apiWriter 替代 #

Wordnik中的这两个Bean负责生成和输出API文档，在Swagger3中无需手动定义——SpringDoc OpenAPI会自动处理文档生成与暴露：默认通过/v3/api-docs接口返回JSON格式文档，/swagger-ui.html提供可视化UI界面。

如果需要自定义文档输出（比如导出到静态文件），可以通过SpringDoc提供的OpenApiResource或调用OpenAPIService生成文档内容，再自行写入文件，无需依赖专门的Writer Bean。

额外注意事项 #

• 移除所有Wordnik相关依赖，引入SpringDoc OpenAPI依赖（Maven示例）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 使用最新稳定版 -->
</dependency>

• 原Wordnik注解（如@Api、@ApiOperation等）可逐步替换为OpenAPI 3注解（@Tag、@Operation等），也可暂时兼容，SpringDoc会自动转换旧注解。

内容的提问来源于stack exchange，提问作者RoboRed