如何在OpenAPI Generator的Mustache模板中使用条件逻辑？

问题场景 #

使用Maven插件形式的OpenAPI OAS3 Java生成器，基于JavaSpring/apiController.mustache模板生成代码时，尝试通过自定义扩展x-generateController控制@Controller注解的生成，但扩展未被识别，无论放在OpenAPI契约的根级别还是端点级别都无效，模板中输出该扩展值为空。

解决步骤 #

1. 修正扩展的放置层级 #

OpenAPI Generator生成Spring控制器时，通常基于tag生成对应控制器类，需将x-generateController扩展放在tags节点下的具体tag对象中，而非根级别或单个端点：

openapi: 3.0.3
tags:
  - name: PetController
    x-generateController: true
    description: 宠物相关操作接口
paths:
  /pet:
    get:
      tags:
        - PetController
      # 其他接口定义

2. 调整模板中扩展的访问路径 #

apiController.mustache的上下文是ApiTemplateModel，控制器对应的标签扩展在tag对象下，需修改模板代码为：

{{#tag.vendorExtensions.x-generateController}}
@Controller("{{classname}}")
{{/tag.vendorExtensions.x-generateController}}

若需默认生成、仅扩展为false时不生成，可反向判断：

{{^tag.vendorExtensions.x-generateController}}
// 不生成@Controller注解
{{/tag.vendorExtensions.x-generateController}}

3. 验证模板上下文变量 #

若不确定扩展层级，可在模板中临时添加代码打印当前上下文所有变量，生成代码后查看输出确认x-generateController的位置：

// 打印当前上下文变量：{{.}}

4. 确保Maven插件正确加载自定义模板 #

检查Maven插件配置，确认templateDirectory指向自定义模板的正确目录，且模板路径与生成器匹配（Spring生成器的模板需放在模板目录/JavaSpring下）：

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>6.6.0</version> <!-- 使用最新稳定版本 -->
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
        <generatorName>spring</generatorName>
        <templateDirectory>${project.basedir}/src/main/resources/openapi-templates</templateDirectory>
        <apiPackage>com.example.api</apiPackage>
        <modelPackage>com.example.model</modelPackage>
      </configuration>
    </execution>
  </executions>
</plugin>

5. 替代方案：基于标签名称的条件控制 #

若自定义扩展仍有问题，可临时通过标签名称做条件判断，例如仅当标签名为PetController时生成注解：

{{#tag.name}}
  {{#eq tag.name "PetController"}}
    @Controller("{{classname}}")
  {{/eq}}
{{/tag.name}}

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