✨ Gilly

Generate Gleam SDKs from OpenAPI specifications.

[!NOTE]
Gilly is in early development:
many features from the OpenAPI specification are not yet supported
for now, generated code is not guaranteed not to break between Gilly releases
Feedback and contributions are very welcome!

Usage

CLI

Add Gilly as a dev dependency in your gleam.toml:

gleam add gilly --dev

Then, you can run Gilly from the command line:

gleam run -m gilly -- <path_to_openapi_spec.json> --output <output_path.gleam>

That's it! You can use the generated SDK in your Gleam projects along with your favorite HTTP client to call the API.

Any HTTP client that uses gleam/http types should be compatible with the Gilly generated client. This includes:

See the examples for fully featured use cases.

Library

Gilly can also be used as a library directly. Please refer to the HexDocs for more details.

Flags

Flag	Short	Description	Default
`--output OUTPUT`	`-o`	Output file path (prints to stdout if omitted)	None
`--optionality OPTIONALITY`		How to determine optional fields: `RequiredOnly` (only fields not listed as required are optional), `NullableOnly` (only fields marked `nullable: true` are optional), `RequiredAndNullable` (fields are optional if either not required or nullable)	`RequiredOnly`
`--indent INDENT`		Number of spaces for indentation	`2`
`--optional-query-params`	`-q`	Make all query parameters optional regardless of the spec	`false`
`--client-default-parameters`		Requests parameters to promote to the Gleam client record rather than passing them directly to each function. Helps reduce boilerplate with APIs where a set of parameters is frequently used. Params will still be overridable via `with_XXX` functions.
`--help`	`-h`	Print help

Examples

Examples of generated clients can be found in the examples directory.

Development

gleam run   # Run the project
gleam test  # Run the tests

This project relies on birdie snapshots for testing. You can update them by running:

gleam run -m birdie

Releases

Releases are handled with goreleaser and GitHub Actions.

To dry-run a release, you can use:

goreleaser release --snapshot --skip=publish --clean

[!NOTE] If you're wondering why the Hex sources don't match the version in gleam.toml, it's because the version in gleam.toml is replaced by GoReleaser during the release process.

References

giacomocavalieri/squirrel an excellent Postgres client generator for Gleam, which inspired the design of this project.
oapi-codegen a Go code generator for OpenAPI specifications. Extremely similar project (that definitely works better) but does not support Gleam.