io.swagger.codegen.v3插件无法生成Swagger HTML文档求助

核心配置错误点 #

• language参数错误：v3版本的swagger-codegen中，生成Swagger UI风格HTML文档的正确语言参数是html2，而非html。html语言仅生成极简静态文本文档，且易因其他配置被抑制。
• sourceFolder配置无效：sourceFolder用于指定生成文件的输出子目录，你错误地将其设为输入的openapi.yml文件路径，这会干扰插件正常逻辑，应删除或设置为合理的子目录名。
• supportingFiles禁用错误：<supportingFiles>false</supportingFiles>会禁止生成HTML依赖的CSS、JS等资源文件，必须移除该配置（默认值为true）才能生成完整可访问的HTML文档。

修正后的完整插件配置 #

<plugin>
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.35</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yml</inputSpec>
                <!-- 正确指定HTML文档生成语言 -->
                <language>html2</language>
                <!-- 建议输出到target目录，避免污染源码资源 -->
                <output>${project.basedir}/target/generated-docs</output>
                <configOptions>
                    <!-- 可选：指定生成文档的子目录，默认会在output下生成html2文件夹 -->
                    <sourceFolder>swagger-docs</sourceFolder>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

验证步骤 #

1. 执行命令：mvn clean swagger-codegen:generate（单独执行生成目标，排除install阶段其他任务干扰）
2. 查看输出目录：target/generated-docs/swagger-docs（或默认的target/generated-docs/html2），其中的index.html就是完整的Swagger UI风格文档，直接在浏览器打开即可访问。

额外说明 #

• 若需生成无交互的轻量化静态HTML，可改用html语言，但需确保移除supportingFiles=false配置，此时会生成单一HTML文件。
• 输出目录建议设置在target下，避免将生成的文档提交到代码仓库，保持源码目录整洁。

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