如何基于springdoc-openapi生成带Try it out功能的Swagger文档且无冗余注解

核心思路：利用springdoc自动能力+非侵入式配置 #

springdoc-openapi本身就支持基于Spring MVC原生注解的自动文档生成，无需大量Swagger专属注解，以下是具体可行方案：

1. 依赖原生Spring注解，让springdoc自动扫描生成基础文档 #

springdoc可以自动识别@GetMapping/@PostMapping等请求注解，以及@PathVariable/@RequestBody/@RequestParam等参数注解，甚至能自动解析实体类的字段信息。

• 确保引入springdoc依赖（以Maven为例）：

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

• 在application.properties中启用基础配置：

springdoc.api-docs.enabled=true
springdoc.swagger-ui.enabled=true

• 实体类中无需@ApiModelProperty，用Jackson原生注解替代：比如用@JsonIgnore忽略不需要展示的字段，用@JsonProperty指定字段别名，这些都会被springdoc识别并同步到文档中。

2. 用配置类集中管理文档元数据，避免业务代码污染 #

通过自定义@Configuration类，使用springdoc的OpenAPI模型类统一配置文档的标题、版本、标签、全局参数等信息，不用在业务接口上加@Tag/@Operation等注解。

示例配置类：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户管理REST API")
                        .version("v1.0")
                        .description("提供用户的CRUD及权限管理接口"))
                .tags(List.of(
                        new Tag().name("用户接口").description("用户信息查询、创建、更新接口"),
                        new Tag().name("权限接口").description("角色、权限配置接口")
                ))
                .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
                .components(new Components()
                        .addSecuritySchemes("bearerAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));
    }
}

3. 用JavaDoc补充API说明，替代Swagger注解 #

springdoc支持解析JavaDoc内容作为API的描述信息，既不用加Swagger注解，还能同时完善代码注释。

示例接口写法：

/**
 * 根据用户ID查询用户详情
 * @param userId 要查询的用户ID（必须为已存在的用户ID）
 * @return 包含用户基本信息及角色列表的DTO
 */
@GetMapping("/users/{userId}")
public UserDetailDTO getUserDetail(@PathVariable Long userId) {
    // 业务逻辑实现
}

• 启用JavaDoc解析：在application.properties中添加配置：

springdoc.api-docs.resolve-schema-properties=true
springdoc.swagger-ui.display-operation-id=true

4. 解决静态openapi.yml的「Try it out」失效问题 #

如果你已经导出了openapi.yml并移除了代码注解，只需在静态文件中补充servers配置，指定实际的后端服务地址，就能让Swagger UI的「Try it out」指向正确的接口：

示例openapi.yml的servers配置：

servers:
  - url: http://localhost:8080
    description: 本地开发环境
  - url: https://your-production-domain.com
    description: 生产环境

同时确保静态文件中的paths与后端实际接口路径完全一致，且后端服务处于运行状态，这样「Try it out」就能正常发起请求。

总结 #

优先采用「原生Spring注解+配置类+JavaDoc」的组合，既能彻底避免Swagger注解污染业务代码，又能让springdoc自动生成完整的可交互文档。静态openapi.yml方案适合需要离线文档但仍保留交互能力的场景，核心是确保静态文档的服务地址和接口路径与后端一致。

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