Openapi 生成器无法使用枚举生成查询参数

Question

我正在尝试生成一个将枚举作为查询参数的服务，但它不断生成错误。 这是 yaml 的部分：

      name: language
      in: query
      description: language
      schema:
        type: string
        enum:
        - en
        - de

我在参数中使用它：

        - $ref: '#/components/parameters/language'

我得到的错误是：

[ERROR] .../api/TestApi.java:[110,65] illegal start of type
[ERROR] .../api/TestApi.java:[110,66] ')' expected
[ERROR] .../api/TestApi.java:[110,82] ';' expected

代码如下所示：

public Response getByLanguage( @PathParam("id") Long id, , allowableValues="en, de" @QueryParam("language") String language

这是我的插件：

                <plugin>
                    <groupId>org.openapitools</groupId>
                    <artifactId>openapi-generator-maven-plugin</artifactId>
                    <version>5.0.1</version>
                    <configuration>
                        <inputSpec>${basedir}/src/main/resources/openapi.yaml</inputSpec>
                        <output>${project.build.directory}/generated-sources/java</output>
                        <generatorName>jaxrs-resteasy-eap</generatorName>
                        <modelPackage>com.openapi.example.model</modelPackage>
                        <apiPackage>com.openapi.example.api</apiPackage>
                        <generateSupportingFiles>false</generateSupportingFiles>
                        <configOptions>
                            <sourceFolder>openapi</sourceFolder>
                            <dateLibrary>java8</dateLibrary>
                            <interfaceOnly>true</interfaceOnly>
                            <java8>true</java8>
                            <serializableModel>true</serializableModel>
                            <useTags>true</useTags>
                            <performBeanValidation>true</performBeanValidation>
                            <useBeanValidation>true</useBeanValidation>
                        </configOptions>
                    </configuration>
                    <executions>
                        <execution>
                            <phase>generate-resources</phase>
                            <id>generate</id>
                            <goals>
                                <goal>generate</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>

我设法让它工作的唯一方法是将它作为一个枚举值数组，但这不是我在这里需要的。

编辑：我在项目中定义的依赖项：

        <dependency>
            <groupId>org.apache.maven.shared</groupId>
            <artifactId>maven-dependency-analyzer</artifactId>
            <version>1.11.1</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-jaxrs</artifactId>
            <version>1.5.8</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>2.1.5</version>
            <scope>compile</scope>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-jsr310</artifactId>
            <version>2.11.3</version>
        </dependency>

Answer 1

生成器中存在多个长期存在的枚举错误（据我所知，适用于所有语言）。

例如https://github.com/OpenAPITools/openapi-generator/issues/4300

而且.. https://github.com/OpenAPITools/openapi-generator/issues/2645

Answer 2

试试下面的演示 yaml。

枚举应定义为 enum: [en, de]。

openapi: 3.0.2
info: {title: Demo Info., description: Demo Description., version: 1.0.0}
servers:
- {url: 'https://something.com', description: Demo Description.}
paths:
  /something:
    post:
      tags: [Something]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SomethingRequest'}
      parameters:
      - {$ref: '#/components/parameters/language'}
      responses:
        200:
          description: OK
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SomethingResponse'}
components:
  parameters:
    language:
      name: language
      schema:
        type: string
        enum: [en, de]
        default: en
      in: query
  schemas:
    SomethingRequest:
      properties:
        demo: {type: string}
    SomethingResponse:
      properties:
        demo: {type: string}

Answer 3

这取决于您使用的是什么生成器，但是在查询参数中使用枚举时 jaxrs-resteasy-eap 会损坏。

我认为这个提交导致了问题。

作为我项目中的临时修复，我将 queryParams.mustache 模板文件编辑为：

{{#isQueryParam}}{{#useBeanValidation}}{{>beanValidationQueryParams}}{{/useBeanValidation}}{{^isContainer}}{{#allowableValues}}@ApiParam(value = "{{{description}}}"{{#required}},required=true{{/required}}, {{> allowableValues }}){{/allowableValues}}{{#defaultValue}} @DefaultValue("{{{.}}}"){{/defaultValue}}{{/isContainer}} @QueryParam("{{baseName}}") {{{dataType}}} {{paramName}}{{/isQueryParam}}

刚刚注意到还有github 这个问题。 从 queryParams.mustache 中删除 allowableValues 的建议可能是 go 的正确方法：

{{#isQueryParam}}{{#useBeanValidation}}{{>beanValidationQueryParams}}{{/useBeanValidation}}{{^isContainer}}{{#defaultValue}} @DefaultValue("{{{.}}}"){{/defaultValue}}{{/isContainer}} @QueryParam("{{baseName}}") {{{dataType}}} {{paramName}}{{/isQueryParam}}

这取决于您如何使用生成器如何使用自己的模板。

我从 npm @openapitools/openapi-generator-cli 使用它，您可以通过在生成命令中添加 -t/--template-dir 选项来应用自己的模板。 这是我的例子：

npx @openapitools/openapi-generator-cli generate -t=templates/jaxrs -i openapi.yaml -o generated/jaxrs -g jaxrs-resteasy-eap -c config-jaxrs.yaml

我刚刚将修改后的 queryParams.mustache 复制到模板/jaxrs 的根目录，生成的 api 函数不再存在双逗号语法问题：

public Response getPets( @ApiParam(value = "My param description", allowableValues="AA, BB, CC") @QueryParam("petType") PetType petType,@Context SecurityContext securityContext);

我还没有使用这些文件，所以我不知道一切是否正确，但至少现在语法是正确的。

更多信息：模板文档