Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chenrui333/rules_openapi
🍃 bazel rules for generating code from openapi specifications
https://github.com/chenrui333/rules_openapi
bazel bazel-rules openapi openapi-gen openapi-specification swagger-codegen
Last synced: 3 days ago
JSON representation
🍃 bazel rules for generating code from openapi specifications
- Host: GitHub
- URL: https://github.com/chenrui333/rules_openapi
- Owner: chenrui333
- License: mit
- Created: 2017-05-17T04:47:26.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-09T19:25:59.000Z (18 days ago)
- Last Synced: 2024-12-24T04:12:34.327Z (3 days ago)
- Topics: bazel, bazel-rules, openapi, openapi-gen, openapi-specification, swagger-codegen
- Language: Starlark
- Size: 88.9 KB
- Stars: 53
- Watchers: 78
- Forks: 25
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI rules for Bazel
[](https://github.com/meetup/rules_openapi/actions)
> [Bazel](https://bazel.build/) rules for generating sources and libraries from [openapi](https://www.openapis.org/) schemas.
- [Rules](#rules)
- [Getting started](#getting-started)
- [OpenAPI generator](#openapi-generator)
- [openapi_gen](#openapi_gen)
## Rules
* [openapi_gen](#openapi_gen)
## Getting started
To use the OpenAPI rules, add the following to your projects `WORKSPACE` file
```python
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:
```python
load("@io_bazel_rules_openapi//openapi:openapi.bzl", "openapi_gen")
```
## OpenAPI generator
By default the code will be generated using [Swagger's codegen](https://github.com/swagger-api/swagger-codegen#swagger-code-generator) it is however possible to switch
to [OpenAPI's generator](https://github.com/OpenAPITools/openapi-generator). This can be done by passing some parameters to the `openapi_repositories` function:
WORKSPACE:
```python
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
```python
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](https://github.com/swagger-api/swagger-codegen#swagger-code-generator) which defines many [configuration options](https://github.com/swagger-api/swagger-codegen#to-generate-a-sample-client-library). Not all configuration options
are implemented in these rules yet but contributions are welcome. You can also request features [here](https://github.com/meetup/rules_openapi/issues/new?title=I%20would%20like%20to%20see...)
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
```python
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"]
)
```