Spring Boot项目中能否用配置文件替代Controller类中的Swagger注解

目前完全可以实现Controller层无任何Swagger/OpenAPI相关注解，所有接口文档配置统一在外部维护，以下是两种可落地的实现方案：

方案1：基于SpringDoc OpenAPI的编程式配置（推荐） #

现在Swagger2已经停止维护，官方推荐使用SpringDoc OpenAPI v3替代，它原生支持通过OpenAPI、OperationCustomizer等组件全局配置所有接口的文档信息，完全不需要在Controller上加任何注解。
注意：SpringDoc 2.x版本适配Spring Boot 3.x，如果使用Spring Boot 2.x需要引入1.x版本的SpringDoc依赖

配置示例 #

1. 首先引入SpringDoc依赖（如果之前用的是Swagger2先替换掉）

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

2. 编写独立的Swagger配置类，所有接口文档信息都在这里定义：

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("项目接口文档").version("1.0"))
                // 全局统一配置请求头，比如Authorization、自定义头，不需要每个接口单独加
                .components(new Components()
                        .addParameters("Authorization", new Parameter()
                                .in("header")
                                .name("Authorization")
                                .description("访问令牌")
                                .required(true)
                                .example("Bearer access_token")
                                .schema(new StringSchema()))
                        .addParameters("X-Custom-Header", new Parameter()
                                .in("header")
                                .name("X-Custom-Header")
                                .description("自定义请求头")
                                .required(true)
                                .example("my header example")
                                .schema(new StringSchema())))
                .paths(new Paths()
                        // 配置/person 接口的信息
                        .addPathItem("/person", new PathItem()
                                .get(new Operation()
                                        .summary("返回人员列表")
                                        .description("查询所有人员信息接口")
                                        // 绑定上面定义的全局请求头
                                        .addParametersItem(new Parameter().$ref("#/components/parameters/Authorization"))
                                        .addParametersItem(new Parameter().$ref("#/components/parameters/X-Custom-Header"))
                                        .responses(new ApiResponses()
                                                .addApiResponse("200", new ApiResponse()
                                                        .description("请求成功")
                                                        .content(new Content()
                                                                .addMediaType("application/json", new MediaType()
                                                                        .example(new ArrayList<>()))))))));
    }
}

这种方式所有配置都集中在这一个配置类里，Controller层完全不需要加任何Swagger相关注解，代码非常干净。

方案2：基于外部properties/yaml配置 #

如果想要完全用配置文件维护，不需要写Java配置代码，SpringDoc也支持直接加载外部的OpenAPI yaml/properties配置文件：

1. 在resources目录下新建openapi.yml文件，按照OpenAPI 3.0的规范编写所有接口文档配置：

openapi: 3.0.1
info:
  title: 项目接口文档
  version: 1.0
paths:
  /person:
    get:
      summary: 返回人员列表
      parameters:
        - name: Authorization
          in: header
          required: true
          description: 访问令牌
          example: "Bearer access_token"
        - name: X-Custom-Header
          in: header
          required: true
          description: 自定义请求头
          example: "my header example"
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              example: []

2. 在application.yml中添加配置指定加载该文件：

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    url: /openapi.yml

这种方式完全不需要写Java配置，所有接口文档都在yaml配置文件里维护，Controller层完全无侵入。

原Swagger2适配方案 #

如果你还在使用旧的Swagger2，也可以通过自定义Docket的globalOperationParameters配置全局请求头，再通过OperationBuilderPlugin扩展点自定义读取外部配置文件的接口描述信息，同样可以实现Controller无注解，不过更推荐升级到SpringDoc来简化实现。

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