tt

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

Background

With OpenAPI design finalized upfront, we can achieve:

• Efficiency: automated generation of server stubs and client SDKs saves development time.
• Consistency: ensures server and client code align with a predefined contract, reducing mismatches.
• Maintainability: changes to the API are made in the specification, automatically reflecting in generated code.
• Scalability: standardized specs facilitate integration and adoption by multiple clients or services.

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 Flakes. If you're not using nix, it's required to manually install tools listed in the packages section of flake.nix. Otherwise you can just run the following command to enter dev environment:

# `nix develop` needs to be run every time you `cd` in.
cd THIS_REPO && nix develop

nix-direnv is highly recommended. It automatically runs nix develop every time you cd to the project.

# `dirnev allow` needs to be run only once.
# After that, when you `cd` in, nix dev env will be automatically loaded.
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.

# Note: edit ./.env file per your preference.
cp ./example.env ./.env
# Run tt-http-app and dependent services.
docker compose up -d
# Run OpenAPI contract tests by Arazzo.
just arazzo

Explore

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

Available recipes:
    arazzo # run OpenAPI contract tests by Arazzo
    build  # build the docker image for the local machine's platform
    buildp # build multi-platform docker images (linux/amd64,linux/arm64)
    bundle # bundle OpenAPI Specifications in to a single file
    doc    # generate API documentation as an HTML file
    gen    # generate server stubs with rust-axum generator
    lint   # lint OpenAPI Specifications
    run    # run the openapi server in debug mode