https://github.com/whisperpine/tt
An OpenAPI driven rust server.
https://github.com/whisperpine/tt
axum docker openapi openapi-generator postgresql redoc server
Last synced: 3 months ago
JSON representation
An OpenAPI driven rust server.
- Host: GitHub
- URL: https://github.com/whisperpine/tt
- Owner: whisperpine
- License: mit
- Created: 2025-06-29T13:11:11.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-10T22:09:00.000Z (12 months ago)
- Last Synced: 2025-07-11T00:44:00.284Z (12 months ago)
- Topics: axum, docker, openapi, openapi-generator, postgresql, redoc, server
- Language: Rust
- Homepage: https://whisperpine.github.io/tt/
- Size: 85 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
tt
[](https://github.com/whisperpine/tt/blob/main/LICENSE)
[](https://github.com/whisperpine/tt/actions/workflows/checks.yml)
[](https://github.com/whisperpine/tt/actions/workflows/build.yml)
[](https://github.com/whisperpine/tt/releases)
[](https://github.com/whisperpine/tt/deployments/openapi-docs)
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](./openapi/) work as the *Single Source of Truth*:
- Design and write OAS ([OpenAPI Specifications](https://www.openapis.org/)) files.
- Generate server stubs (axum is used in this repo) by [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator).
- Lint OAS files by [redocly](https://github.com/Redocly/redocly-cli)
and generated HTML which is deploy on [GitHub Pages](https://whisperpine.github.io/tt/).
- Run contract tests by [Arazzo](https://www.openapis.org/arazzo-specification),
generated by [redocly](https://github.com/Redocly/redocly-cli)
according to OpenAPI Specifications.
```mermaid
flowchart LR
oas(OpenAPI
Specifications):::red_stroke
ttopen("tt-openapi
(Server Stubs)")
ttcore("tt-http-core
(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
(The App)")
end
db("DB")
ttapp --- db
classDef red_stroke stroke: #f66
style csdk stroke-dasharray: 2
style cc stroke-dasharray: 2
```
## Prerequisites
Dev environment is managed by [nix-direnv](https://github.com/nix-community/nix-direnv),
which stitches nix flakes and [direnv](https://github.com/direnv/direnv).
It automatically sets up environment variables and runs `nix develop` every time
you `cd` into the project directory.
```sh
# 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:
```sh
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:
```txt
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
```