如何解决无法自定义swagger codegen生成代码的HTML与CSS的问题

核心实现思路 #

Swagger Codegen 本质是基于模板引擎渲染输出内容，只要调整生成过程的模板读取优先级，让工具优先加载你自定义的HTML、CSS文件，就能完成个性化调整，全程不需要修改工具的全局安装文件。

分步骤实操流程 #

• 建立独立的自定义模板目录：不要直接修改Swagger Codegen安装路径下的内置模板文件，否则后续工具版本升级时，所有自定义修改会被默认文件覆盖，在本地单独创建用于存放自定义模板的文件夹。
• 按需拷贝需要调整的模板：从Codegen内置的静态API文档模板资源中，把你需要修改的HTML布局文件、CSS样式文件复制到本地自定义目录，不需要全量拷贝所有模板文件，仅保留需要调整的内容即可，减少后续维护成本。
• 配置生成过程的模板读取规则：
  • 命令行直接执行代码生成的场景：调用生成命令时追加t/--templates参数，指定本地自定义模板目录的绝对路径，示例可复用的命令：
    swagger-codegen generate -i 你的OpenAPI配置文件路径 -l html2 -o 最终输出目录路径 -t 本地自定义模板目录的绝对路径
  • Maven/Gradle 构建集成场景：在Swagger Codegen插件的配置节点中新增templateDirectory属性，值指向本地自定义模板目录路径，构建时工具会优先读取该目录下的模板文件，找不到匹配文件时才会回退使用内置默认模板。

自定义调整的关键注意点 #

• 修改HTML结构时，不能删除模板中原有的动态占位符标记（比如接口路径、入参列表、响应示例的动态渲染占位内容），否则会导致最终生成的文档无法正常填充接口动态信息。
• 调整CSS样式时，既可以直接在拷贝出来的CSS模板文件中修改原有规则，也可以在HTML模板的头部新增自定义CSS引入标签，完全不需要改动工具内置的默认样式文件。
• 如果需要完全替换默认的样式体系，只需要在自定义目录中放置和内置模板同名的CSS文件，生成时会直接覆盖默认样式内容，不需要额外的适配配置。

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