Skip to content

🍃 bazel rules for generating code from openapi specifications

License

Notifications You must be signed in to change notification settings

meetup/rules_openapi

Repository files navigation

OpenAPI rules for Bazel

Workflow Status

Bazel rules for generating sources and libraries from openapi schemas.

Rules

Getting started

To use the OpenAPI rules, add the following to your projects WORKSPACE file

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

RULES_OPEN_API_COMMIT = "f0f42afb855139ad5346659d089c32fb756d068e" # see compatibility matrix
RULES_OPEN_API_SHA256 = "9570186948f1f65c61d2c6c6006840ea70888b270f028bbd0eb736caae1cd9df" # see compatibility matrix

http_archive(
    name = "io_bazel_rules_openapi",
    strip_prefix = "rules_openapi-%s" % RULES_OPEN_API_COMMIT,
    url = "https://github.com/meetup/rules_openapi/archive/%s.tar.gz" % RULES_OPEN_API_COMMIT,
    sha256 = RULES_OPEN_API_SHA256
)

load("@io_bazel_rules_openapi//openapi:openapi.bzl", "openapi_repositories")
openapi_repositories()

Then in your BUILD file, just add the following so the rules will be available:

load("@io_bazel_rules_openapi//openapi:openapi.bzl", "openapi_gen")

Bazel compatibility matrix

Bazel version rules_openapi commit sha256 hash
1.2.1 32527fd4f9b4a50199b3905d34027b1eaf61b88a 700feae8dda1a6400672c77e0b2bc2d5db9a21b902c20b342d65bb314af953f3
2.0.0 c6e77e314df7ced9652bc68f3ee32d5425160716 ba55fbd75a50eb8e2fd08d4dc72a8f32858bc14db184677cee969453d72d7c67
2.1.0 c289e0b4e127924e2a18bc8f345b6cf1945735de f88a6627533d2974385b36ce1f3606795cd08070e28e5e44074ed2101afdd348
2.1.1 4e35a7b968908213e3c6eedc4435d140dbb577b3 d1af6e9bd23b24a07f059b1a97f0bc305d7cf74a2965f06fc11c182d568a0e1c
2.2.0 08e2472385e8929a21bf8cd747f26e3b933dbd2f 9dfeeb8cef2347b5ba3d59b7948fd26518eefc537ca95d4846d6c124e38d294a
3.0.0 2528ecbfe628211de87e1924908350014fb0d03e d4c5b924f0a2a7d844650ff3b76c0475f370e5ceb5b1811665144102e7296383
3.6.0 112663e9935f4711c7c14c3357f8e4547d43cd8c cf32217fda600e49848cd9b496a2e77e50d695230f437f8d5a2f0f2f5d437338
3.7.0 f0f42afb855139ad5346659d089c32fb756d068e 9570186948f1f65c61d2c6c6006840ea70888b270f028bbd0eb736caae1cd9df
3.7.1 896323d32a19078e83a70513077554a6529b18b7 dca86aea8e76ae891bedf42dbb91a7d4b573efc7142cb6049d6b061768c43701
4.0.0 d39cf5731254bbf6ef973228bb6f5f4050aa7e60 264808b5fa537806fe78ac67a41cb6e0b14e63e67981b3058c5a6758675e7e4f
4.1.0 89882964f041a9d11bdc48299defdd500e3e1995 89ab3a0c8190d5c88c3bd19d16585153b4ce5aba3a47cdefdc5eee63f4bd813a
4.2.1 8b33d29996d539937e11f7da22f85047fab01197 e76d5e3a807a5eae6d7059393759869336a5f649906b64c488e1ada89675908a
5.0.0 f48152c4a204b1b9c59d726579ce416aa5d08732 1d6bdad4608e99708cc7818ffdca9d5ae4c74857d002f19330ae8a028868f258

OpenAPI generator

By default the code will be generated using Swagger's codegen it is however possible to switch to OpenAPI's generator. This can be done by passing some parameters to the openapi_repositories function:

WORKSPACE:

load("@io_bazel_rules_openapi//openapi:openapi.bzl", "openapi_repositories")
openapi_repositories(
    codegen_cli_version = "5.0.0",
    codegen_cli_sha256 = "839fade01e54ce1eecf012b8c33adb1413cff0cf2e76e23bc8d7673f09626f8e",
    codegen_cli_provider = "openapi"
)

For most languages, changing the generator should be seamless. You might however need to change the language field in you rule to match one available on the selected generator.

openapi_gen

openapi_gen(name, spec, api_package, model_package, invoker_package)

This generates a .srcjar archive containing generated source files from a given openapi specification.

These rules rely on swagger-codegen which defines many configuration options. Not all configuration options are implemented in these rules yet but contributions are welcome. You can also request features here

Attributes
name Name, required

A unique name for this rule.

spec String, required

Path to .yaml or .json file containing openapi specification

language String, required

Name of language to generate.

If you wish to use a custom language, you'll need to create a jar containing your custom codegen module, then use deps to add the custom codegen module to the classpath.

Note, not all swagger codegen provided languages generate the exact same source given the exact same set of arguments. Be aware of this in cases where you expect bazel not to perform a previous executed action for the same sources.

api_package String, optional

package for api.

module_package String, optional

package for models.

invoker_package String, optional

package for invoker.

additional_properties Dict of strings, optional

Additional properties that can be referenced by the codegen templates. This allows setting parameters that you'd normally put in config.json, for example the Java library template:

    language = "java",
    additional_properties = {
        "library": "feign",
    },
system_properties Dict of strings, optional

System properties to pass to swagger-codegen. This allows setting parameters that you'd normally set with -D, for example to disable test generation:

    language = "java",
    system_properties = {
        "apiTests": "false",
        "modelTests": "false",
    },
type_mappings Dict of strings, optional

Allows control of the types used in generated code with swagger-codegen's --type-mappings parameter. For example to use Java 8's LocalDateTime class:

    language = "java",
    additional_properties = {
        "dateLibrary": "java8",
    },
    type_mappings = {
        "OffsetDateTime": "java.time.LocalDateTime",
    },

An example of what a custom language may look like

java_import(
  name = "custom-scala-codegen",
  jars = ["custom-scala-codegen.jar"]
)

openapi_gen(
  name = "petstore-client-src",
  language = "custom-scala",
  spec = "petstore-spec.json",
  api_package = "com.example.api",
  model_package = "com.example.model",
  invoker_package = "com.example",
  deps = [
    ":custom-scala-codegen"
  ]
)

scala_library(
  name = "petstore-client",
  srcs = [":petstore-client-src"]
)