Skip to content

๐Ÿƒ bazel rules for generating code from openapi specifications

License

Notifications You must be signed in to change notification settings

chenrui333/rules_openapi

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

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")

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"]
)