OpenAPI Generator类命名、响应Map及Swagger UI树形示例配置问题

以下是我的translation.yml文件：

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
  - url: http://localhost:8088/
    description: Generated server url
paths:
  /api/translation/{module}/{locale}:
    get:
      tags:
        - translations
      summary: Get translations by module, locale and tenantId
      operationId: getTranslations
      parameters:
        - name: module
          in: path
          required: true
          schema:
            type: string
        - name: locale
          in: path
          required: true
          schema:
            type: string
        - name: tenantId
          in: query
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Get the translations
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
              example:
                nav:
                  payments:
                    invoice:
                      details:
                        title: Payments Details
                        all: AllPayments
                      orders: Orders
                      dashboard: Dashboard
                    title: Payments
                  home:
                    title: Home

以下是pom.xml中的相关配置：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.5.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>
                    ${project.basedir}/src/main/resources/translation.yml
                </inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>test.inbound_api</apiPackage>
                <modelPackage>test.inbound_api.model</modelPackage>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

• 生成的接口名称为ApiApi.java，如何将其生成为TranslationApi.java？已解决
• 生成的接口方法返回类型为ResponseEntity<Map<String, String>>，如何使其返回ResponseEntity<Map<String, Object>>？已解决
• 如何正确配置树形结构的example？当前在Swagger UI中仅显示Example Value "string"，该example在Swagger Editor中可正常展示树形结构，但未出现在生成的接口类中，我期望实现树形示例效果。

问题3解决方案 #

当前Swagger UI无法正确展示树形示例，核心原因是你的OpenAPI定义里，返回结果的schema指定additionalProperties的类型为string，但实际示例是嵌套的多层对象结构，schema和示例不匹配，导致Swagger UI只能按字符串类型渲染示例。

解决步骤：

1. 修改OpenAPI的schema定义，使其支持嵌套的树形结构（既可以包含字符串值，也可以包含子对象），使用递归的schema来匹配你的示例结构：

   openapi: 3.0.1
   info:
     title: OpenAPI definition
     version: v0
   servers:
     - url: http://localhost:8088/
       description: Generated server url
   paths:
     /api/translation/{module}/{locale}:
       get:
         tags:
           - translations
         summary: Get translations by module, locale and tenantId
         operationId: getTranslations
         parameters:
           - name: module
             in: path
             required: true
             schema:
               type: string
           - name: locale
             in: path
             required: true
             schema:
               type: string
           - name: tenantId
             in: query
             required: true
             schema:
               type: integer
               format: int64
         responses:
           '200':
             description: Get the translations
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/TranslationTree'
                 example:
                   nav:
                     payments:
                       invoice:
                         details:
                           title: Payments Details
                           all: AllPayments
                         orders: Orders
                         dashboard: Dashboard
                       title: Payments
                     home:
                       title: Home
   components:
     schemas:
       TranslationTree:
         type: object
         additionalProperties:
           oneOf:
             - type: string
             - $ref: '#/components/schemas/TranslationTree'
   

2. 重新生成代码：运行OpenAPI Generator，此时生成的接口返回类型会匹配递归的树形结构（和你问题2中已解决的ResponseEntity<Map<String, Object>>一致）。
3. 验证Swagger UI：重启应用后，Swagger UI会正确识别嵌套的示例结构，展示出你期望的树形示例效果。

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