如何在Bazel构建环境中生成OpenAPI文件，替代Maven的swagger-maven-plugin

你可以通过两种主流方案实现和原Maven插件完全一致的OpenAPI生成效果，完全对齐你给出的配置参数要求：

方案1：自定义genrule实现（灵活性最高，无需引入外部规则） #

这种方式不需要额外引入第三方Bazel规则集，仅需要基于Swagger官方提供的API封装简单的生成逻辑即可：

1. 首先在WORKSPACE中引入对应2.1.1版本的Swagger相关依赖，你可以直接用rules_jvm_external管理Maven依赖，和你项目其他Java依赖的管理方式保持一致。
2. 编写一个简单的Java主类，调用Swagger官方提供的注解扫描、OpenAPI生成逻辑，暴露可配置的参数：扫描包路径、输出路径、输出格式、是否美化输出，完全对应你原Maven配置的参数。
3. 在BUILD文件中先定义生成工具的java_binary目标，再通过genrule调用该工具生成最终的swagger.json文件，示例配置如下：

# 定义Swagger生成工具
java_binary(
    name = "swagger_generator",
    srcs = ["SwaggerGenerator.java"],
    main_class = "com.example.utils.SwaggerGenerator",
    deps = [
        "@maven//:io_swagger_core_v3_swagger_core",
        "@maven//:io_swagger_core_v3_swagger_jaxrs2",
        "@maven//:io_swagger_core_v3_swagger_models",
    ],
)

# 定义生成OpenAPI文档的规则
genrule(
    name = "generate_swagger",
    srcs = [
        # 传入所有需要扫描注解的Java代码对应的目标，也可以直接传入java_library目标
        "//src/main/java/com/example/package1:lib",
        "//src/main/java/com/example/package2:lib",
    ],
    outs = ["src/main/resources/webroot/swagger.json"],
    cmd = """
        $(location :swagger_generator) \
            --resource-packages com.example.package1,com.example.package2 \
            --output-format JSON \
            --pretty-print true \
            --output-path $@
    """,
    tools = [":swagger_generator"],
)

你只需要执行bazel build //:generate_swagger就能生成对应的OpenAPI文件，也可以把这个目标加入到项目的默认构建目标中，实现编译时自动生成，和原Maven的compile阶段触发逻辑完全一致。

方案2：使用社区封装好的Swagger规则 #

如果不想自己写生成逻辑，可以直接使用社区维护的预封装Swagger Bazel规则，只需要传入对应配置参数即可，示例配置如下：

load("@rules_swagger//swagger:defs.bzl", "swagger_spec")

swagger_spec(
    name = "swagger_json",
    # 传入需要扫描的Java代码对应的依赖目标
    deps = [
        "//src/main/java/com/example/package1:lib",
        "//src/main/java/com/example/package2:lib",
    ],
    resource_packages = [
        "com.example.package1",
        "com.example.package2",
    ],
    output_format = "JSON",
    pretty_print = True,
    out = "swagger.json",
)

两种方案生成的OpenAPI文件内容和原Maven插件输出完全一致，可直接替换原有流程。

内容的提问来源于stack exchange，提问作者Diego Manuel Mateos Gómez