在 OpenApi 3.0 中生成一个属性作为模式定义

Question

使用 swagger 2.0 时，java.util.Currency class 作为单独的定义生成。但是当我们生成 OpenAPI 3.0 时，我们运行遇到了 swagger-core 将其生成为属性.

的问题

从 classes

生成 OpenAPI 3.0 规范

我们有 f.e。这个 class:

import java.util.Currency; 

public class Wrapper {
   private Currency currency;
}

根据这段代码，我们使用以下插件配置生成 openapi 规范：

      <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.0.9</version>
            <configuration>
                <outputFileName>openapi</outputFileName>
                <outputFormat>YAML</outputFormat>
                <outputPath>....</outputPath>
                <resourcePackages>...</resourcePackages>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

生成后将生成此组件定义：

components:
  schemas:
    Wrapper:
      type: "object"
      properties:
        currency:
          type: object
          properties:
            currencyCode:
              type: string
            defaultFractionDigits:
              type: integer
              format: int32
            numericCode:
              type: integer
              format: int32
            displayName:
              type: string
            symbol:
              type: string

根据 OpenAPI 3.0 规范生成 classes

然后我们使用以下插件在另一个项目中生成 classes：

生成此 openapi 规范的 classes 的代码：

        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>3.2.0</version>
            <executions>
                <execution>
                    <id>openapi-generation</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>${project.basedir}/src/main/resources/swagger.yaml</inputSpec>
                        <language>java</language>
                        <library>jersey2</library>
                        <generateSupportingFiles>false</generateSupportingFiles>
                        <configOptions>
                            <booleanGetterPrefix>is</booleanGetterPrefix>
                            <dateLibrary>threetenbp</dateLibrary>
                            <import-mappings>
                                Currency=java.util.Currency
                            </import-mappings>
                        </configOptions>
                        <generateApis>false</generateApis>
                        <generateApiDocumentation>false</generateApiDocumentation>
                        <generateModelTests>false</generateModelTests>
                        <generateModelDocumentation>false</generateModelDocumentation>
                    </configuration>
                </execution>
            </executions>
        </plugin>

这将产生一个名为 WrapperCurrency 的 class。 --import-mappings 选项似乎不起作用，因为它是属性而不是 schema。如果将货币生成为单独的模式定义，这将起作用。

想要的结果

是否有任何方法可以注释属性，使 java.util.Currency 生成为模式？类似于：

components:
  schemas:
    Wrapper:
      type: "object"
      properties:
        currency:
           $ref: "components/schemas/Currency"

    Currency:
      type: object
      properties:
        currencyCode:
          type: string
        defaultFractionDigits:
          type: integer
          format: int32
        numericCode:
            type: integer
            format: int32
        displayName:
          type: string
        symbol:
          type: string

或者有没有办法将 --import-mappings 选项绑定到属性而不是对象？

Answer 1

嗯，您可以考虑一个解决方法：在货币字段中添加注释 @Schema(ref = "Currency") 将使插件跳过生成属性。不幸的是，它也不会为货币 class 生成模式定义：

components:
  schemas:
    Wrapper:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/Currency'

我不确定这对您来说是否是个问题，因为您无论如何都将其映射回 java.util.Currency。但如果是，还有另一种 hack：您可以提供一个带有部分模式的静态文件（只是货币定义）并配置插件以将其与生成的模式（openapiFilePath 参数）合并。

插件配置：

      <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <version>2.0.9</version>
            <configuration>
                ...
                <openapiFilePath>src/main/resources/currency.yaml</openapiFilePath>
                ...
            </configuration>
            ...
      </plugin>

currency.yaml:

components:
  schemas:
    Currency:
      type: object
      properties:
        currencyCode:
          type: string
        defaultFractionDigits:
          type: integer
          format: int32
        numericCode:
          type: integer
          format: int32
        displayName:
          type: string
        symbol:
          type: string

我知道这是一个 hack，但如果没有其他选择...

在 OpenApi 3.0 中生成一个 属性 作为模式定义

Generate a property as schema definition in OpenApi 3.0

java

swagger

openapi

openapi-generator

从 classes

根据 OpenAPI 3.0 规范生成 classes

想要的结果

在 OpenApi 3.0 中生成一个属性作为模式定义