Quarkus下openapi-generator生成带请求响应示例的Ascii文档问题

前置修正 #

首先修正目录拼写错误：你当前写的scr是错误拼写，正确应为src，否则模板无法被插件正常加载。 #

1 调整pom.xml插件配置 #

在原有配置基础上补充示例生成相关的开关，修改后的完整插件配置如下：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.2.1</version>
    <executions>
        <execution>
            <id>generate-ascii-docs</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <globalProperties>
                    <apiDocs>true</apiDocs>
                    <apiModels>true</apiModels>
                    <apiTests>false</apiTests>
                    <modelTests>false</modelTests>
                    <verbose>false</verbose>
                    <!-- 新增：自动生成示例值，即使openapi.yaml没写example也能生成模拟值 -->
                    <generateExampleValues>true</generateExampleValues>
                </globalProperties>
                <inputSpec>${project.basedir}/target/openapi/openapi.yaml</inputSpec>
                <output>${project.basedir}/target/ascii/</output>
                <generatorName>asciidoc</generatorName>
                <generateApiDocumentation>true</generateApiDocumentation>
                <generateModelDocumentation>true</generateModelDocumentation>
                <generateSupportingFiles>true</generateSupportingFiles>
                <groupId>${project.groupId}</groupId>
                <artifactId>${project.artifactId}</artifactId>
                <templateDirectory>${project.basedir}/src/asciidoc/templates</templateDirectory>
                <configOptions>                     
                    <useIntroduction>true</useIntroduction>
                    <delegatePattern>false</delegatePattern>
                    <useMethodAndPath>false</useMethodAndPath>
                    <prependFormOrBodyParameters>false</prependFormOrBodyParameters>
                    <!-- 新增：开启示例生成 -->
                    <generateExamples>true</generateExamples>
                    <!-- 新增：关闭示例跳过开关 -->
                    <skipExamples>false</skipExamples>
                    <!-- 新增：拆分输出为多文件，不把所有接口内容塞到单个adoc里 -->
                    <outputAsSingleFile>false</outputAsSingleFile>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

2 补充Mustache模板文件 #

在src/asciidoc/templates目录下新增两个模板文件，用于生成独立的请求、响应示例文件：

http-request.adoc.mustache 示例内容 #

[source,http]
----
{{httpMethod}} {{path}} HTTP/1.1
Host: {{basePath}}
Content-Type: {{consumes}}
{{#bodyParam}}

{{{example}}}
{{/bodyParam}}
----

http-response.adoc.mustache 示例内容 #

[source,http]
----
HTTP/1.1 {{code}} {{message}}
Content-Type: {{produces}}

{{{example}}}
----

3 调整index.mustache的示例引入逻辑 #

把你原有index.mustache里的Samples部分替换为如下内容，适配独立示例文件的引入：

{{^skipExamples}}
===== Samples

=== 请求示例
include::{{operationId}}_{{httpMethod}}_http-request.adoc[]

=== 响应示例
{{#responses}}
==== {{code}} 响应
include::{{operationId}}_{{httpMethod}}_{{code}}_http-response.adoc[]
{{/responses}}
{{/skipExamples}}

4 可选：自定义示例内容 #

如果你不想用自动生成的模拟值，可以直接在你的OpenAPI 3.0 yaml文件中，为每个接口的请求体、响应体手动配置example字段，生成时会优先使用你手动定义的示例内容。

内容的提问来源于stack exchange，提问作者Lino