在 OpenApi 3.0 中生成一個屬性作為架構定義

Question

使用 swagger 2.0 時， java.util.Currency類作為單獨的定義生成。 但是當我們生成 OpenAPI 3.0 時，我們遇到了 swagger-core 將其作為屬性生成的問題。

---

從類生成 OpenAPI 3.0 規范

我們有這個班級：

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 規范生成類

然后我們使用以下插件在另一個項目中生成類：

生成類的代碼形成了這個 openapi 規范：

        <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的類。 --import-mappings選項似乎不起作用，因為它是 property 而不是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")將使插件跳過生成屬性。 不幸的是，它也不會為 Currency 類生成模式定義：

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

我不確定這對你來說是否是一個問題，因為你無論如何都要將它映射回java.util.Currency 。 但如果是這樣，還有另一個技巧：您可以提供帶有部分架構（僅貨幣定義）的靜態文件，並配置插件以將其與生成的架構（ 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>

貨幣.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

這是一個黑客，我知道，但如果沒有其他選擇......