openapi-generator asciidoc 限制参数列，省略类型

Posted 2023-04-15

【中文标题】openapi-generator asciidoc 限制参数列，省略类型

【英文标题】：openapi-generator asciidoc limits parameter columns, omits type

【发布时间】：2022-01-15 14:16:24

【问题描述】：

有没有办法指定哪些列出现在“参数”部分？例如，我想使用 Schema/type 而不是 Pattern。

我的配置：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.3.0</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>$project.basedir/target/openapi.json</inputSpec>
                <generatorName>asciidoc</generatorName>
                <configOptions>
                    <useIntroduction>true</useIntroduction>
                </configOptions>
                <skipValidateSpec>true</skipValidateSpec>
            </configuration>
        </execution>
    </executions>
</plugin>

这里是相关的源码sn-p：

 /myapi/resourceId:
    get:
      tags:
      - Api Operations
      summary: Get a widget
      description: Get a widget by its resource id
      operationId: findOne
      parameters:
      - name: resourceId
        in: path
        required: true
        schema:
          type: string
      - name: affiliateId
        in: header
        required: false
        schema:
          type: integer
          format: int64
          default: 256

以及相关的输出sn -p：

====== Header Parameters

[cols="2,3,1,1,1"]
|===
|Name| Description| Required| Default| Pattern

| affiliateId
|  
| -
| 256
| 

|===

而不是“模式”列，我希望它显示类似 Schema 的内容以及整数和/或 int64 的值。

【参考方案1】：

我通过编辑小胡子模板解决了这个问题：

克隆openapi-generator项目后，我从模块（link）下的src/main/resources/asciidoc-documentation找到以下两个文件：params.mustache和param.mustache，复制到我自己的/src/main/resources/openapi下的项目中。

然后我打开params.mustache 并进行了从“模式”到“数据类型”的查找和替换。

同样在param.mustache 中，我将“pattern”替换为“dataType”

然后在openapi-generator-maven-plugin 的maven pom 文件插件配置中，我在configuration 元素下添加了以下元素：

<templateDirectory>$project.basedir/src/main/resources/openapi</templateDirectory>

运行 mvn clean compile 会产生所需的输出：

[cols="2,3,1,1,1"]
|===
|Name| Description| Required| Default| Data Type

| affiliateId
|  
| -
| 256
| Long

注意：为了获得正确的模型字段名称，我在配置元素下启用了调试：<verbose>true</verbose> 然后发出命令（类似于）：mvn org.openapitools:openapi-generator-maven-plugin:5.3.0:generate@my-execution-id -pl mysubmodule -X -l out.txt;打开out.txt，搜索“headerParams”或“affiliateId”，找到数据类型对应的字段名，我这里有“dataType”和“dataFormat”，我选择了前者。

另外请注意，我不需要将index.mustache 或model.mustache 等复制到我的项目中，只需将上面提到的两个模板文件。