OpenAPI Generator 如何用 .openapi-generator-ignore 跳过指定文件的生成【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator用 OpenAPI Generator 根据 OpenAPI 规范v2、v3生成客户端或服务端代码时生成结果里常常包含一些你并不想要的文件——例如git_push.sh、整套测试、文档等。如果希望指定文件或目录在生成时被跳过、重新生成时也不被覆盖官方机制是在输出目录根部放置一个.openapi-generator-ignore文件。语法与.gitignore、.dockerignore一致比--skip-overwrite这类“整体不覆盖”的参数粒度更细可以对单个文件、目录分别指定。ignore 文件放在哪里根据 docs/customization.md 的说明.openapi-generator-ignore文件必须存在于输出目录的根部即生成命令-o参数指定的目录该文件默认由工具自动生成见 docs/faq-extending.md“The ignore file works just like .gitignore, and it is auto-generated by default.”所以首次生成之后你只需要在输出目录里编辑这份已存在的文件后续每次重新生成都会继续遵守其中的规则文档同时指出ignore 文件“allows for better control over overwriting existing files than the--skip-overwriteflag”即它解决的问题比--skip-overwrite更精确你可以只忽略部分文件其余文件照常更新。规则语法哪些文件会被跳过docs/customization.md 给出了完整的规则示例以下代码块为文档原文# OpenAPI Generator Ignore # Lines beginning with a # are comments # This should match build.sh located anywhere. build.sh # Matches build.sh in the root /build.sh # Exclude all recursively docs/** # Explicitly allow files excluded by other rules !docs/UserApi.md # Recursively exclude directories named Api # You cant negate files below this directory. src/**/Api/ # When this file is nested under /Api (excluded above), # this rule is ignored because parent directory is excluded by previous rule. !src/**/PetApiTests.cs # Exclude a single, nested file explicitly src/Org.OpenAPITools.Test/Model/AnimalFarmTests.cs各条规则的实际效果规则文档给出的含义build.sh匹配任意位置下的build.sh/build.sh只匹配根目录下的build.shdocs/**递归排除整个docs目录!docs/UserApi.md显式允许被其他规则排除的文件src/**/Api/递归排除所有名为Api的目录其下的文件无法再用!规则豁免具体嵌套文件路径精确排除单个文件需要特别注意文档中的限制一旦父目录被前面的规则排除目录内文件的!豁免规则会失效示例中!src/**/PetApiTests.cs就是因为src/**/Api/已排除父目录而不生效。写规则时先想清楚排除层级避免豁免落空。如果只是跳过单个脚本最小示例见 docs/faq-extending.md——在输出目录根部的.openapi-generator-ignore中写入# Prevent generator from creating these files: git_push.sh首次生成时如何让规则生效ignore 文件要“存在于输出目录”才生效但首次生成时输出目录还没有这个文件。文档给出两条路径方式一--ignore-file-override指向已有的 ignore 文件CLI 选项--ignore-file-overridepathMaven 插件与 Gradle 插件中对应参数名为ignoreFileOverride指向一个已存在的文件其内容会按相对输出目录的方式求值docs/faq-extending.md、docs/usage.md。例如先准备一份ignore.txt再执行openapi-generator generate \ -i petstore.yaml \ -g spring \ -o /tmp/spring \ --ignore-file-override /tmp/spring-ignore.txt注意文档的提醒docs/customization.md这是一个完全覆盖complete override——在之后重新生成代码时它会覆盖输出目录中原有的.openapi-generator-ignore文件。适合首次生成建立规则的场景不适合作为长期参数保留。方式二--openapi-generator-ignore-list一次性预填条目如果希望在生成过程中直接把一批条目写进.openapi-generator-ignore可以用全局选项openapiGeneratorIgnoreListCLI 形式为--openapi-generator-ignore-list值用逗号分隔。docs/customization.md 给出的示例命令如下其中 jar 路径与 spec 路径为该文档针对仓库构建产物与自带测试资源的写法作为文档示例保留java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \ -g spring \ -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml \ -o /tmp/spring \ --additional-properties useTagstrue \ --openapi-generator-ignore-list README.md,pom.xml,docs/*.md,src/main/java/org/openapitools/model/*这里README.md、pom.xml、docs/*.md、src/main/java/org/openapitools/model/*就是要预写入 ignore 文件的条目。生成完成后输出目录中会带有这些条目的.openapi-generator-ignore后续生成直接沿用或再手工编辑即可。如何验证用--dry-run预览文件操作改完规则后不必真跑一次生成来检查。docs/debugging.md 说明 CLI 支持--dry-run选项可以不改动文件系统地查看工具计划执行的文件操作。例如openapi-generator generate \ -i petstore.yaml \ -g spring \ -o /tmp/spring \ --dry-run输出中的 “Dry Run Results” 部分会逐行列出将被处理的文件每行首字母是文件状态。文档给出的状态含义如下States: - w Write - n Write if New/Updated - i Ignored - s Skipped Overwrite - k Skipped by user option(s) - e Error evaluating file write state判断方法目标文件若被 ignore 规则命中会显示为iIgnoredn表示仅在新建或内容变化时写入w表示一定会写入。确认被跳过的文件都标记为i后再去掉--dry-run执行正式生成即可。文档中的 dry-run 输出以 lua 生成器为例以下截取 docs/debugging.md 中的文档示例其中路径为文档作者的本地路径仅作示例Dry Run Results: k /Users/williamcheng/Code/openapi-generator/samples/client/petstore/lua/.openapi-generator-ignore n /Users/williamcheng/Code/openapi-generator/samples/client/petstore/lua/.openapi-generator/VERSION k /Users/williamcheng/Code/openapi-generator/samples/client/petstore/lua/spec/api_response_spec.lua ...示例中该场景下所有文件均为kSkipped by user option(s)来自--minimal-update等用户选项并不包含i状态行它的作用是展示输出格式而不是i状态的样例。实际验证时以你自己命令输出中目标文件的状态字符为准。边界与迁移注意事项位置限制文件必须放在输出目录根部放在子目录或不写-o对应的目录都不会被读取。豁免限制被排除目录下的文件不能再被!规则豁免规则顺序和层级要想清楚见上文表格。override 的覆盖性--ignore-file-override在重新生成时会覆盖输出目录里已有的.openapi-generator-ignore文档明确建议只在首次生成时使用“Most useful on initial generation.”docs/usage.md。从 swagger-codegen 迁移如果你原来用的是.swagger-codegen-ignore按 docs/migration-from-swagger-codegen.md它已被.openapi-generator-ignore取代且文件内部语法不变不需要手工重命名——当目录中没有.openapi-generator-ignore而存在.swagger-codegen-ignore时OpenAPI Generator 在运行时会自动考虑并重命名它。与全局属性的关系docs/global-properties.md 中supportingFiles、models、apis、apiDocs、modelDocs、apiTests、modelTests等全局属性用于按大类裁剪生成范围文档对它们的建议都是 “Prefer using the more robust.openapi-generator-ignore”——即精细跳过优先用 ignore 文件全局属性只适合粗粒度开关。完成配置后验证方式就是上文--dry-run输出中被跳过的文件均显示iIgnored正式生成时这些文件不会被写入输出目录中已有的同名文件也不会被覆盖。相关文档可继续参阅 docs/customization.md 的 “Ignore file format” 一节、docs/faq-extending.md 的 “How do I skip files during code generation?” 以及 docs/debugging.md 的 “Generation” 一节。【免费下载链接】openapi-generatorOpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)项目地址: https://gitcode.com/GitHub_Trending/op/openapi-generator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考