gnr8

Generate OpenAPI 3.1 and typed client SDKs from your API source code.

gnr8 reads routes, handlers, and types from a service. It builds one language-neutral API graph and uses that graph to generate an OpenAPI document and client SDKs. A local Rust crate in .gnr8/ defines the pipeline. There is no YAML, TOML, or JSON configuration file.

gnr8 is an OAIZ Labs open-source project maintained by OAIZ.

Status: Early release candidate. The current source frontends are Go with Gin, Python with FastAPI or Flask typed envelopes, and TypeScript with NestJS class DTOs.

• One pipeline: Source extraction, the API graph, OpenAPI generation, and SDK generation use one owned contract.
• Code is the source of truth: gnr8 reads native routes and types. It does not require a separate annotation dialect.
• Code-based configuration: Edit ordinary Rust in .gnr8/src/main.rs to select sources, transforms, targets, and post-processors.
• Deterministic output: Identical input produces byte-identical output. Incremental generation writes only changed artifacts.
• Local operation: The CLI and pipeline run on your machine or in CI. There is no hosted control plane.

service source
    │  routes, handlers, types, and native documentation
    ▼
language-neutral API graph
    ├──► OpenAPI 3.1
    ├──► Go SDK
    ├──► Python SDK
    └──► TypeScript SDK

The graph is the source of truth. OpenAPI documents and SDKs are output artifacts. Facts that the source cannot express, such as a service-wide security scheme, come from transforms in the .gnr8/ crate.

Targets include OpenAPI 3.1 YAML and typed Go, Python, and TypeScript SDKs. Go uses net/http. TypeScript uses the built-in fetch API. Python uses urllib; its models use Pydantic v2 by default or standard-library dataclasses when selected in the pipeline.

Install the latest CLI release:

curl -fsSL https://raw.githubusercontent.com/oaiz-io/gnr8/main/scripts/install.sh | bash

The release archive contains the CLI and its extractor resources. You also need:

• Rust and Cargo, because gnr8 compiles the local .gnr8/ crate.
• The toolchain for the source language that gnr8 analyzes.
• Access to the Cargo registry for the first build, unless the required crates are already cached.

The crates.io package named gnr8 is the Rust SDK used by the .gnr8/ crate. It is not the CLI. See the install guide for release layouts, local installation, and resource discovery.

From the root of a Go and Gin service:

gnr8 init --source go-gin --sdk go

This command creates .gnr8/src/main.rs. Edit the generated pipeline when you need different inputs, metadata, outputs, or custom stages:

use gnr8::sdk::prelude::*;

fn main() -> std::process::ExitCode {
    gnr8::worker::run(
        Pipeline::new()
            .source(GoGin::new().inputs(["."]))
            .transform(SetBasePath::new("/books"))
            .transform(SetTitle::new("Bookstore API"))
            .transform(ApplySecurity::api_key("ApiKeyAuth", "X-API-Key"))
            .target(OpenApi31::new().to("generated/openapi.yaml"))
            .target(GoSdk::new().module("example.com/bookstore/sdk").to("generated/sdk"))
            .post(Header::generated()),
    )
}

Generate and check the artifacts:

gnr8 generate
gnr8 doctor
gnr8 check
gnr8 verify

Use gnr8 init --source fastapi --sdk python, --source flask --sdk python, or --source nestjs --sdk typescript for the other source stacks.

The official Action runs gnr8 check and fails when committed artifacts are stale:

name: gnr8

on: [push, pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  check-generated:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: oaiz-io/gnr8@v0.12.0 # first release with API change reporting
        with:
          setup-go: "true"
          report-api-changes: "true"

Without pull-requests: write, reports remain in the job summary and uploaded artifact. Fork PRs use those surfaces regardless of the permissions block; see the fork publishing recipe.

Pin an exact released tag. For Python and TypeScript sources, use the matching setup input. See Artifacts and CI for all inputs and multi-project examples.

gnr8 generate compiles and runs Rust code from .gnr8/ with your user permissions. Review this code before you run it. --no-build prevents a build, and --no-execute prevents both build and execution.

Source extraction is static. gnr8 does not import or run the analyzed service. Dynamic or unresolved routes and types produce a diagnostic or an explicit error.

• Install: release archives, local installation, and toolchains.
• Agent documentation index: task-based routes for coding agents.
• CLI reference: commands, flags, output, and exit behavior.
• Pipeline configuration: built-in stages and custom Rust stages.
• Source extraction: supported patterns and limits.
• SDK generation: Go, Python, and TypeScript targets.
• Full reference: detailed behavior and type mapping.
• Examples: complete inputs and committed generated output.

gnr8 is under active development. Issues and pull requests are welcome. Read the contribution guide and the engineering invariants before you submit a change, and run make check. Report security problems as described in the security policy.

gnr8 is available under the MIT License. The license keeps the original author notice and records OAIZ as the current project steward.