openapi-nexus 0.1.3

OpenAPI 3.x multi-language code generator
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

# Architecture

## Pipeline

```mermaid
flowchart TD
    A["OpenAPI YAML / JSON"] --> B

    B["Parser
    Parses YAML/JSON into ParsedSpec
    Auto-detects OAS 3.0 / 3.1 / 3.2"]

    B --> C

    C["IR Lowering
    Lowers ParsedSpec into IrSpec
    Version-agnostic IR"]

    C --> D

    D["CodeGenerator::generate()
    Each generator receives &IrSpec
    Returns Vec<FileInfo>"]

    D --> E

    E["FileWriter::write_files()
    Writes files to disk"]
```

Lowering happens once in the orchestrator (`src/generators/orchestrator.rs`). Generators never touch raw OpenAPI types.

## Module Layout

openapi-nexus is a single crate. All modules live under `src/`:

```
src/
├── cli/              CLI argument parsing and entry point
├── codegen/          CodeGenerator/FileWriter traits, GeneratorType, Language enums
├── config/           Configuration loading (CLI > env > TOML > defaults)
├── ir/               IrSpec types and lowering passes
│   └── lower/        v30.rs, v31.rs, v32.rs
├── spec/             Raw OAS types (v30, v31, v32)
├── parser/           YAML/JSON parsing, OAS version auto-detection
└── generators/       One submodule per generator
    ├── typescript/fetch/
    ├── go/http/
    ├── rust/common/         Shared model + API emission for Rust backends
    ├── rust/reqwest/
    ├── rust/ureq/
    ├── rust/aioduct/
    ├── python/common/       Shared model + API emission for Python backends
    ├── python/httpx/
    ├── python/requests/
    ├── java/okhttp/
    ├── kotlin/okhttp/
    ├── orchestrator.rs      Orchestrates parse → lower → generate → write
    └── registry.rs          Maps GeneratorType to constructor
```

## The CodeGenerator Trait

```rust
pub trait CodeGenerator {
    fn language(&self) -> Language;
    fn generator_type(&self) -> GeneratorType;
    fn generate(&self, ir: &IrSpec) -> Result<Vec<FileInfo>, Box<dyn Error + Send + Sync>>;
}
```

`CombinedGenerator` is a blanket impl of `CodeGenerator + FileWriter`. The orchestrator stores generators as `Box<dyn CombinedGenerator + Send + Sync>` and calls `generate()` then `write_files()`.

## Code Emission

All generators use [sigil-stitch](https://github.com/adamcavendish/sigil-stitch), a type-safe code generation framework. sigil-stitch provides:

- Language-specific type systems (TypeScript, Go, Rust, Python, Java, Kotlin)
- Import tracking and deduplication
- Width-aware pretty printing
- The `sigil_quote!` macro for inline code templates with `$if`, `$for`, `$let` directives

Each generator's `sigil_emit*.rs` files contain the emission logic that transforms IR types into sigil-stitch AST nodes.