使用OpenAPI Generator生成Spring代码时参数示例缺失问题排查

使用openapi-generator-maven-plugin 6.6.0以设计优先模式生成REST API，已在官方编辑器中检查open-api.yaml文件，无语法错误且示例显示正常，但通过Maven生成代码并部署服务后，Swagger UI中所有示例均缺失，请问可能的原因是什么？

相关配置代码 #

open-api.yaml #

openapi: 3.0.3

/user/getUserByName:
  get:
    tags:
      - User
    summary: Get User By Name
    operationId: getUserByName
    parameters:
      - name: name
        in: query
        description: name
        required: true
        schema:
          type: string
          example: John

Maven插件配置 #

<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>${openapi-generator-maven-plugin.version}</version>
<executions>
  <execution>
    <id>server-sources</id>
    <phase>generate-sources</phase>
    <goals>
      <goal>generate</goal>
    </goals>
    <configuration>
      <generatorName>spring</generatorName>
      <generateApiDocumentation>true</generateApiDocumentation>
      <library>spring-boot</library>
      <inputSpec>${project.basedir}/src/main/resources/open-api.yaml</inputSpec>
      <generateApiTests>false</generateApiTests>
      <generateModelTests>false</generateModelTests>
      <supportingFilesToGenerate>ApiUtil.java,SpringDocConfiguration.java</supportingFilesToGenerate>
      <configOptions>
        <delegatePattern>true</delegatePattern>
        <useTags>true</useTags>
        <dateLibrary>java8-localdatetime</dateLibrary>
      </configOptions>
      <packageName>xxx.service</packageName>
      <apiPackage>xxx.api</apiPackage>
      <modelPackage>xxx.model</modelPackage>
    </configuration>
  </execution>
</executions>
</plugin>

Swagger依赖版本 #

<io.swagger.version>1.6.6</io.swagger.version>
<io.swagger.core.v3.version>2.2.8</io.swagger.version>

• Swagger版本冲突：同时引入Swagger 1.x（1.6.6）和Swagger 3.x（2.2.8）依赖，两者分属不同产品线，存在兼容问题。你的API用的是OpenAPI 3.0.3，应该统一用Swagger 3.x（swagger-core v3系列），移除Swagger 1.6.6的所有相关依赖和配置。

• 生成器未开启示例生成：当前插件配置里没有明确启用示例生成的参数。在<configOptions>中添加<useExamples>true</useExamples>，强制生成示例相关的注解和代码，确保Swagger UI能识别到示例数据。

• SpringDoc配置未生效：生成的SpringDocConfiguration.java可能没正确配置示例展示逻辑。检查该配置类，确保它正确初始化了OpenAPI实例；或者手动补充配置，比如通过@OpenAPIDefinition注解完善示例相关设置（更推荐通过生成器配置自动处理）。

• 示例定义位置不兼容：虽然你在schema下定义了example，但部分生成器对示例位置敏感。可以把example移到parameter层级，调整后的yaml片段如下：

  parameters:
    - name: name
      in: query
      description: name
      required: true
      schema:
        type: string
      example: John
  

  调整后生成器能更准确识别并生成对应的示例注解。

内容的提问来源于stack exchange，提问作者Krisztián Szeles