openapi_cr

Crystal port of microsoft/kiota — OpenAPI parser/resource grouper, pre-codegen CodeDOM AST, and Crystal code generator from OpenAPI descriptions.

Upstream source of truth: vendor/kiota pinned at v1.32.2 (git submodule).

Version: 0.2.0 | Specs: 699 (0 failures) | Crystal: >= 1.20.2

What It Does

1. Parses OpenAPI 3.x / Swagger 2.0 specs (JSON/YAML) into a native Crystal model
2. Builds a URL tree (OpenApiUrlTreeNode) mapping API paths to resource namespaces
3. Generates a pre-codegen AST (CodeNamespace, CodeClass, CodeMethod, CodeProperty, CodeType, etc.)
4. Renders Crystal API clients matching kiota's fluent builder pattern

Installation

dependencies:
  openapi:
    github: dsisnero/openapi_cr

CLI Usage

# Build the generator
make build

# Generate a Crystal client
./bin/openapi generate -d spec.yaml -o ./out --client-name ApiClient --models-name Models

Library Usage

require "openapi"
require "openapi/http/stdlib_adapter"
require "openapi/http/auth_provider"

token = ENV["TOKEN"]
auth = BaseBearerTokenAuthenticationProvider.new(BearerTokenAccessTokenProvider.new(token))
adapter = StdlibRequestAdapter.new("https://api.example.com", auth_provider: auth)

# Raw HTTP
ri = RequestInfo.new(http_method: "GET", url_template: "{+baseurl}/users",
  path_parameters: {"baseurl" => "https://api.example.com"})
ri.add_header("Accept", "application/json")

channel = adapter.send(ri, String)
body = channel.receive?
puts body if body

Examples

See openapi_examples/examples/ for working clients:

• create_contacts.cr — MS Graph batch contact creation
• list_contacts.cr — MS Graph paginated contact listing
• cleanup_contacts.cr — MS Graph filtered contact deletion
• github_example.cr — GitHub API repos + pull requests

Development

make install   # shards install
make format    # crystal tool format src spec
make lint      # ameba src spec + format check
make test      # crystal spec (699 specs, 0 failures)
make build     # shards build
make examples  # regenerate openapi_examples clients

Architecture

• src/openapi/ — HTTP layer: request adapter, auth providers, serialization
• src/openapi/http/ — StdlibRequestAdapter, RequestInfo, authentication, middleware
• src/openapi_generator/ — Kiota builder port: model creation, URL tree, refiners
• src/openapi_generator/code_dom/ — Pre-codegen AST types
• src/openapi_generator/codegen/ — Crystal code writers and renderers
• src/serde/ — Serialization/deserialization framework (Serde::Auto)

License

MIT