Skip to content

v0.1.23+doc1

v0.1.23+doc1: feat: add tool to generate code from spec (#75)
@tanmaykm tanmaykm tagged this 18 May 02:54 
Add a few methods that help invoke the code generator providing a spec file and generating Julia code.

The [OpenAPI Generator Docker image](https://hub.docker.com/r/openapitools/openapi-generator-cli) is a code generator that can generate client libraries, server stubs, and API documentation from an OpenAPI Specification. It can also be hosted as a service. OpenAPI.jl will now make use of that to provide a way to generate code. Methos `OpenAPI.generate` will generate code from an OpenAPI specification. It can be pointed at a server hosted on the local machine or a remote server. The OpenAPI Generator must be running at the specified `generator_host`. Returns the folder containing generated code.

```julia
OpenAPI.generate(
    spec::Dict{String,Any};
    type::Symbol=:client,
    package_name::AbstractString="APIClient",
    export_models::Bool=false,
    export_operations::Bool=false,
    output_dir::AbstractString="",
    generator_host::AbstractString=GeneratorHost.Local
)
```

Arguments:
- `spec`: The OpenAPI specification as a Dict. It can be obtained by parsing a JSON or YAML file using `JSON.parse` or `YAML.load`.

Optional arguments:
- `type`: The type of code to generate. Must be `:client` or `:server`. Defaults to `:client`.
- `package_name`: The name of the package to generate. Defaults to "APIClient".
- `export_models`: Whether to export models. Defaults to false.
- `export_operations`: Whether to export operations. Defaults to false.
- `output_dir`: The directory to save the generated code. Defaults to a temporary directory. Directory will be created if it does not exist.
- `generator_host`: The host of the OpenAPI Generator. Defaults to `GeneratorHost.Local` (which points to `http://localhost:8080`).

The `generator_host` can be pointed to any other URL where the OpenAPI Generator is running, e.g. `https://openapigen.myorg.com`. Other possible pre-defined values of `generator_host`, which point to the public service hosted by OpenAPI org are:
- `OpenAPI.GeneratorHost.OpenAPIGeneratorTech.Stable`: Runs a stable version of the OpenAPI Generator at <https://api.openapi-generator.tech>.
- `OpenAPI.GeneratorHost.OpenAPIGeneratorTech.Master`: Runs the latest version of the OpenAPI Generator at <https://api-latest-master.openapi-generator.tech>.

A locally hosted generator service is preferred by default for privacy reasons. One can be started on the local machine using `OpenAPI.openapi_generator`. It uses the `openapitools/openapi-generator-online` docker image and requires docker engine to be installed. Use `OpenAPI.stop_openapi_generator` to stop the local generator service after use.

```julia
OpenAPI.openapi_generator(;
    port::Int=8080,         # port to use
    use_sudo::Bool=false    # whether to use sudo while invoking docker
)

OpenAPI.stop_openapi_generator(;
    use_sudo::Bool=false    # whether to use sudo while invoking docker
)
```
Assets 2
Loading