oaspec

Generate usable Gleam code from OpenAPI 3.x specifications.

oaspec is aimed at practical, typed code generation rather than a feature checklist. It handles the OpenAPI cases that tend to break real projects, such as $ref resolution, allOf, oneOf and anyOf, deepObject query parameters, form bodies, multipart bodies, and multiple security schemes, while failing fast when a spec goes outside the supported subset.

• Generate client and server-side modules from a single spec
• Produce readable Gleam types, encoders, decoders, request types, and response types
• Handle real-world OpenAPI patterns: unions, nullable fields, additionalProperties, form bodies, multipart, and security
• Backed by 470 unit tests, ShellSpec CLI tests, 40 integration compile tests, and 178 test fixtures (including 94 OSS-derived edge-case specs)

Why oaspec

• Built for Gleam: the generated code is shaped like normal Gleam modules, not generic templates awkwardly translated from another ecosystem.
• Focused on practical OpenAPI: coverage is strongest around the features teams actually ship with, not just toy Petstore specs.
• Strict by default: unsupported features are reported explicitly instead of being silently dropped into broken output.

What you get

Given one OpenAPI spec, oaspec generates modules you can keep in your repository:

gen/my_api/
  types.gleam
  decode.gleam
  encode.gleam
  request_types.gleam
  response_types.gleam
  middleware.gleam
  guards.gleam          (only if schemas have validation constraints)
  handlers.gleam
  router.gleam

gen_client/my_api/
  types.gleam
  decode.gleam
  encode.gleam
  request_types.gleam
  response_types.gleam
  middleware.gleam
  guards.gleam          (only if schemas have validation constraints)
  client.gleam

Example generated code:

/// A pet in the store
pub type Pet {
  Pet(
    id: Int,
    name: String,
    status: PetStatus,
    tag: Option(String),
  )
}

pub type PetStatus {
  PetStatusAvailable
  PetStatusPending
  PetStatusSold
}

pub fn create_pet(config: ClientConfig, body: types.CreatePetRequest)
  -> Result(response_types.CreatePetResponse, ClientError) {
  // ...
}

pub fn list_pets(req: request_types.ListPetsRequest)
  -> response_types.ListPetsResponse {
  let _ = req
  panic as "unimplemented: list_pets"
}

Quickstart

Install from GitHub release

Requires Erlang/OTP 27+.

curl -fSL -o oaspec https://github.com/nao1215/oaspec/releases/latest/download/oaspec
chmod +x oaspec
sudo mv oaspec /usr/local/bin/

Build from source

Requires Gleam 1.15+, Erlang/OTP 27+, and rebar3.

git clone https://github.com/nao1215/oaspec.git
cd oaspec
gleam deps download
gleam run -m gleescript
sudo mv oaspec /usr/local/bin/

Generate code

1. Create a config file.

oaspec init

2. Edit oaspec.yaml.

input: openapi.yaml
package: my_api
output:
  dir: ./gen

3. Run the generator.

oaspec generate --config=oaspec.yaml

You can also run gleam run -- generate --config=oaspec.yaml.

Configuration

Generated server code is written to <dir>/<package>. Generated client code is written to <dir>_client/<package>. The basename of each output directory must match package so imports such as import my_api/types resolve correctly.

CLI options:

--config=<path>   Path to config file (default: ./oaspec.yaml)
--mode=<mode>     server, client, or both (default: both)
--output=<path>   Override output base directory

Best For

• Generating typed Gleam clients from an OpenAPI contract
• Keeping request and response types in sync with an external API spec
• Bootstrapping server-side types, handlers, and router support from the same source spec
• Catching unsupported spec features early in CI instead of after code generation

OpenAPI Support

oaspec supports OpenAPI 3.0.x and a practical subset of OpenAPI 3.1 in YAML or JSON.

Coverage is strongest in these areas:

• Schemas: component schemas, primitive aliases, enums, nullable fields, arrays, objects, allOf, oneOf, anyOf, and typed additionalProperties
• References: local $ref resolution for schemas, parameters, request bodies, responses, and path items, including circular-reference detection
• Parameters: path, query, header, and cookie parameters, including array serialization and style: deepObject
• Request bodies: application/json, application/x-www-form-urlencoded, and multipart/form-data
• Responses: typed status-code variants, $ref responses, default responses, and text or binary passthrough cases
• Security: apiKey, HTTP auth schemes, OAuth2, and OpenID Connect
• Generation safety: name collision handling, keyword escaping, validation guards, and capability errors with clear failure modes

Current Boundaries

These boundaries are generated from the capability registry in src/oaspec/capability.gleam.

These are the most important limitations today:

• The following keywords are detected and rejected: $defs, prefixItems, if/then/else, dependentSchemas, not, unevaluatedProperties, unevaluatedItems, contentEncoding, contentMediaType, contentSchema, mutualTLS
• xml annotations are not handled by the parser
• Some fields are parsed and preserved but not yet used by codegen: webhooks, externalDocs, tags, examples, links, operation servers, path servers, response headers, encoding
• The following are normalized to supported equivalents:
• const: String const normalized to single-value enum
• type: [T, null]: Normalized to nullable
• type: [T1, T2]: Normalized to oneOf

Development

This project uses mise for tool versions and just as a task runner.

mise install
just check
just shellspec
just integration

Test structure:

License

MIT