Spring Boot项目Swagger显示占位符而非实际项目信息的问题求助

我在Spring Boot项目中配置Swagger时遇到了一个棘手的问题：Swagger文档里始终显示@project.name@、@project.version@、@project.description@、@{operation.tag}这类占位符，完全没有替换成实际的项目信息和配置值。

我的配置文件与项目基础信息 #

application.properties

info.app.artifact=@project.artifactId@
info.app.name=@project.name@
info.app.description=@project.description@
info.app.version=@project.version@

api-documentation.properties

operation.tag=Operation_Name
operation.desc=This operation is to retrieve records from database.

pom.xml核心项目配置

<artifactId>my-project</artifactId>
<version>${major.number}.${minor.number}.${build.number}-${tag}</version>
<name>my-project</name>

我已尝试的解决方案（均无效） #

1. 启用application.properties的Maven资源过滤

<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

2. 在pom.xml的properties节点定义占位符

<properties>
  <project.name>My Project Name</project.name>
  <project.description>Spring boot based project to test swagger</project.description>
  <project.version>1.0.0-SNAPSHOT</project.version>
</properties>

3. 配置Maven资源插件使用@作为占位符分隔符

<build>
  <plugins>
    <plugin>
      <artifactId>maven-resources-plugin</artifactId>
      <version>3.2.0</version>
      <configuration>
        <delimiters>
          <delimiter>@</delimiter>
        </delimiters>
        <useDefaultDelimiters>false</useDefaultDelimiters>
      </configuration>
    </plugin>
  </plugins>
</build>

额外排查与解决建议 #

根据我处理这类问题的经验，你可以再检查以下几个容易被忽略的点：

1. 确认Maven构建的执行流程

一定要通过mvn clean package或mvn clean install命令完成构建，再启动项目。如果直接用IDE的“Run”按钮启动，很多IDE默认不会触发Maven的资源过滤逻辑——你可以先手动执行mvn process-resources生成过滤后的配置文件，再用IDE启动，或者在IDE的Maven配置里勾选“启用资源过滤”选项。

2. 避免与Maven内置变量命名冲突

Maven本身内置了project.name、project.version这些变量，对应pom.xml里的<name>、<version>节点。你在properties里手动定义的同名变量可能会被Maven内置值覆盖，导致过滤结果不符合预期。
建议把properties里的变量名改成自定义前缀，比如：

<properties>
  <app.name>My Project Name</app.name>
  <app.description>Spring boot based project to test swagger</app.description>
  <app.version>1.0.0-SNAPSHOT</app.version>
</properties>

然后在application.properties里对应修改：

info.app.name=@app.name@
info.app.description=@app.description@
info.app.version=@app.version@

3. 验证Swagger配置类的读取逻辑

检查你的Swagger配置类（比如OpenApiConfig）是否正确读取了info.app.*配置项，而不是直接硬编码占位符。举个正确的配置例子：

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "${info.app.name}",
        version = "${info.app.version}",
        description = "${info.app.description}"
    ),
    tags = {
        @Tag(name = "${operation.tag}", description = "${operation.desc}")
    }
)
public class OpenApiConfig {
}

另外，要确保Spring能正确解析这些${...}占位符——如果配置类里用了@Value注入，要确认注入的变量值是正确的，没有还是占位符。

4. 检查过滤后的配置文件实际内容

构建完成后，去项目的target/classes目录下打开生成的application.properties，看看里面的占位符是否已经被替换成实际值：

• 如果这里还是占位符：说明Maven资源过滤根本没生效，要再检查pom.xml的资源配置（比如是否有多个resource节点、过滤范围是否正确）
• 如果这里已经是实际值，但Swagger依然显示占位符：问题出在Swagger的配置读取环节，要排查配置类的注解或注入逻辑

5. 处理@{operation.tag}这类Swagger注解占位符

注意到你还有@{operation.tag}的问题，这类占位符如果是写在Swagger的@Operation或@Tag注解里，要确保Spring能正确从api-documentation.properties读取配置——如果这个文件没开启Maven过滤（如果里面有占位符的话），或者配置类没正确加载这个配置文件，也会导致占位符显示。可以在配置类上添加@PropertySource("classpath:api-documentation.properties")来确保这个配置被加载。

6. 升级Maven资源插件版本

你当前用的是3.2.0版本的maven-resources-plugin，这个版本有点旧了，试试升级到最新稳定版（比如3.3.1），旧版本可能存在一些占位符解析的边界问题：

<plugin>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.3.1</version>
  <configuration>
    <delimiters>
      <delimiter>@</delimiter>
    </delimiters>
    <useDefaultDelimiters>false</useDefaultDelimiters>
  </configuration>
</plugin>

内容来源于stack exchange