tt

Generate rust server stubs based on OpenAPI Specifications, reduce boilerplates and ensure consistency.

Background

With OpenAPI design finalized upfront, we can achieve:

• Efficiency: save development time by automatically generate server stubs and client SDKs.
• Consistency: ensure server and client code align with a predefined contract, reducing mismatches.
• Maintainability: make changes to the API in the specification first, work on auto-generated code later.

How It Works

OAS files under ./openapi work as the Single Source of Truth:

• Design and write OAS (OpenAPI Specifications) files.
• Generate server stubs (axum is used in this repo) by openapi-generator-cli.
• Lint OAS files by redocly and generated HTML which is deploy on GitHub Pages.
• Run contract tests by Arazzo, generated by redocly according to OpenAPI Specifications.

flowchart LR
  oas(OpenAPI<br>Specifications):::red_stroke
  ttopen("tt-openapi<br>(Server Stubs)")
  ttcore("tt-http-core<br>(Server Impl)")
  csdk("Client SDK")
  cc("Client App")
  arazzo("Arazzo Configurations")
  web("API Web Page")

  oas -->|openapi-generator| ttopen
  ttopen --> ttcore
  ttcore --> ttapp
  oas -->|openapi-generator| csdk
  csdk --> cc
  cc -.-> ttapp
  oas -->|redocly| arazzo
  arazzo -.->|contract tests| ttapp
  oas -->|redocly| web

  subgraph services
    ttapp("tt-http-app<br>(The App)")

  end

  db("DB")
  ttapp --- db

  classDef red_stroke stroke: #f66
  style csdk stroke-dasharray: 2
  style cc stroke-dasharray: 2

Loading

Prerequisites

Dev environment is managed by nix-direnv, which stitches nix flakes and direnv. It automatically sets up environment variables and runs nix develop every time you cd into the project directory.

# You only need to run `dirnev allow` ONCE after git clone.
# Then every time you `cd`, the dev environment will be loaded automatically.
cd THIS_REPO && dirnev allow

Get Started

Host the service locally by docker and run OpenAPI contract tests:

git clone THIS_REPO && cd THIS_REPO

# Setup dev environment described in the "Prerequisites" above,
# or at least install these tools: just, redocly, rust toolchain.

# Run the backend application and dependent services.
just spin-up
# Run OpenAPI contract tests by Arazzo (in ANOTHER terminal).
just arazzo

Explore

Run just -l to see commonly used commands in this repo:

Available recipes:
    [OpenAPI]
    arazzo  # run OpenAPI contract tests by Arazzo
    bundle  # bundle OpenAPI Specifications in to a single file
    doc     # generate API documentation as an HTML file
    lint    # lint OpenAPI Specifications

    [Rust]
    gen     # generate server stubs with rust-axum generator
    run     # run the openapi server in debug mode
    spin-up # spin up docker compose services and run the backend app

    [SQL]
    fix     # fix SQL linting errors found by sqlfluff