ProjectsFastAPI & OpenAPI tooling

FastSpec

Open-source app for writing, versioning, diffing and linting OpenAPI specs, with an MCP server so AI agents can work with them. FastAPI and Vue, self-hosted from one Docker image or serverless on AWS for cents a month.

Highlights

Overview

FastSpec is a web app for writing and maintaining OpenAPI specs. You build a spec in a form or as YAML or JSON, preview it in Swagger UI, save it as named versions, diff any two of them, and lint it with Spectral against your own house rules. An MCP server lets AI agents such as Claude Code or Cursor read, write, version and lint your specs with a scoped API key.

FastSpec's lint view shows the Bookstore API at 58 out of 100 with 14 warnings. In Claude Code, the prompt 'Fix the lint warnings in my Bookstore API spec on FastSpec, then save it as version 1.1.0' calls FastSpec's MCP tools (get_spec_details, lint_spec, validate_spec, save_spec_version), and FastSpec then shows 100 out of 100 with no issues.
Claude Code fixes a spec's 14 lint warnings through FastSpec's MCP tools and saves it as version 1.1.0. The score goes from 58 to 100. Fictional data.

It is the spec-first counterpart to FastMock, which mocks an API from the models a FastAPI app already declares. FastSpec has been open source (AGPL-3.0) since v0.1.0 on 27 September 2026. It runs from one Docker image, or as a hosted version at fastspec.kaseovo.com. Every screenshot below comes from the app running locally against fictional specs.

Problem

  • OpenAPI is easy to get subtly wrong by hand. Path parameters, $refs and array item schemas all have to line up, and Swagger UI often fails quietly when they don’t.
  • Reviewers need changes in API terms. “An endpoint was removed” and “a schema field became required” matter; a JSON text diff buries them.
  • Custom lint rules are a code execution risk. Spectral rulesets can load JavaScript from disk and fetch other rulesets from URLs, so accepting them from users as-is means running their code on the server.
  • AI clients need their own credential. Handing an assistant the user’s web session is not acceptable; access has to be scoped and revocable.
  • Trying it has to take one command. Until September 2026, running it locally meant an AWS emulator, the AWS CDK and a Google OAuth client of your own.
  • It is a side project. The AWS bill has to be close to zero when nobody is using it, without giving up a real managed Postgres.

Approach

I built FastSpec with AI coding agents in the loop (Claude Code, and GitHub’s Copilot agent for some issues), so the repo is written to be read by an agent as much as by me. AGENTS.md lists the test commands and what the common failures mean, CONTEXT.md is a glossary of domain terms (Path Parameter Token, Lint Ruleset, Spec Version Mode), and every architecture decision is an ADR. Once the feature set was in place I ran a full-repo review and worked through it.

The rule the codebase follows throughout: the why lives next to the code. Module docstrings point at the ADR or review section that explains them. database.py, for example, cites ADR-0009 for why the hosted database’s quota errors get their own message instead of “try again shortly”. A deliberate trade-off then can’t get “fixed” by accident, by me or by an agent.

Going open source followed the same habit. docs/ROADMAP.md records each decision with its reason (license, sign-in, database, what to do with the git history) and ticks off the work as it lands. Every release has a changelog entry.

What I built

Form editorDoneA full spec can be built without touching JSON, and path parameters can't drift from the path string.

GoalLet someone write a complete OpenAPI spec without knowing its JSON shape by heart, with the code and a live Swagger preview one click away.

The editor is three views over one spec object: a form, the code in Monaco (YAML or JSON), and a Swagger UI preview. Most of the work went into the form. Info, servers, paths, tags, component schemas and security each get a section with search, and adding a path, an operation or a schema goes through a short wizard instead of an empty JSON block.

In FastSpec's form editor, the Add New Path wizard adds GET /authors (List authors, listAuthors) in five steps. The code view then shows the spec as YAML next to the Swagger UI preview, and saving as version 1.2.0 opens a recap with one path added and a lint score of 100 out of 100.
Adding GET /authors with the Add Path wizard, checking it in the YAML view and the live preview, then saving version 1.2.0 after the recap. Fictional data.

Path parameters are the one thing the form won’t let you edit directly. Type /loans/{loanId}/return and a required loanId path parameter appears; remove the token and the parameter goes too, after a confirmation if you had filled it in. The path string is the only source, so the two can’t disagree.

FastSpec form editor showing the Bookshelf API paths, with the POST /loans/{loanId}/return operation expanded on its Parameters step and a required loanId path parameter.
The loanId parameter was created from the {loanId} token in the path, and only changes through it. Fictional data.
Versions and diffDoneAny two versions, or a draft and a version, diff by endpoint, schema, server and info, and export as Markdown.

GoalMake every save a reviewable change: show what moved between two versions, or between a draft and what's stored, before anything is written.

Every spec keeps named versions. The backend diff compares two of them in API terms: endpoints added, removed or modified, schema fields added, removed or changed, plus servers and info. The same comparison runs against an unsaved draft, which is what the save dialog uses. Before anything is written, you see what changed and the lint score the new version would get. The report also exports as Markdown, for a PR description or a changelog.

Version history drawer comparing two Bookshelf API versions: four additions, two modifications and one removal, with the added POST /loans endpoints and Loan schema listed.
Two saved versions compared: loan endpoints and a Loan schema added, a member endpoint removed. Fictional data.
Save dialog recap showing Changes: 0 added, 1 modified, 0 removed, and Lint: score 68/100 with 9 issues.
The save recap for a draft that fixes a missing operationId and edits a summary. The lint score goes from 65 to 68. Fictional data.
Linting with custom rulesDoneSpecs lint against Spectral's OpenAPI rules plus named custom rulesets, with no path to run user code.

GoalCatch spec problems before an API consumer does, with house rules a team can write without learning Spectral's YAML and without being able to run code on the server.

Linting runs the Spectral CLI, installed in the backend’s Docker image, against a stored spec or an unsaved draft. Spectral’s spectral:oas rules always apply. On top of them, a user keeps any number of named rulesets, marks one as the default, and can pin another to a specific spec: a strict one for a public API, a looser one for an internal one. In the code view, each finding’s marker is placed by its JSON path, so it lands on the right line in YAML and in JSON.

Rules are built in a form (severity, a JSONPath target from presets, a function and its options), with a raw YAML tab for what the form can’t express. “Test against current spec” runs one draft rule on its own, without the baseline rules, so you see exactly what it matches before saving.

Lint results for the Bookshelf API scoring 65 out of 100, mixing Spectral baseline warnings with a custom operation-id-required error and a tags-alphabetical info finding.
Baseline Spectral findings next to two custom rules: operation-id-required (error) and tags-alphabetical (info). Fictional data.
Custom ruleset dialog with the operation-id-required rule expanded, showing severity, function, JSONPath target, message, and a Test against current spec button reporting 1 match.
Testing a draft rule against the open spec before saving the ruleset. Fictional data.

Rule functions

Chose
Spectral's ten built-in functions only
Instead of
Custom JavaScript functions
Why
Spectral loads custom functions from disk and runs them. Accepting them from users would be remote code execution, so raw YAML with functions or functionsDir is rejected at save time.

extends

Chose
Only spectral: rulesets
Instead of
Any extends target
Why
extends can point at a URL, which would let a user make the server fetch arbitrary addresses (SSRF).

Ruleset scope

Chose
Many named rulesets per user, one default, an optional pin per spec
Instead of
One ruleset per user
Why
A public API and an internal one rarely want the same rules. Resolution is the spec's pinned ruleset, else the default, else the baseline alone.
MCP server for AI clientsDoneAn API key scoped by action reads, writes, versions, compares and lints its owner's specs through eleven MCP tools.

GoalLet an AI assistant work with a user's specs directly, with a credential the user can scope and revoke, and without ever touching their web session.

A FastMCP server runs in the same app at /mcp. It started with three read tools (who_am_i, get_saved_specs_for_user and get_spec_details). v0.1.0 added tools to create and delete specs, list, read and save versions, compare two of them, validate and lint, all reusing the services behind the HTTP API.

AI clients never see the web session. Instead, a user creates an API key in the app, picks what it may do (read:specs, write:versions, lint:specs and so on), and adds it with the MCP URL to their client. Each tool declares the actions it needs, and a middleware checks them before the call runs.

New API Key dialog for a key named Cursor with read:specs and read:versions, showing the raw key once and the MCP server URL to paste into an AI client.
The raw key is shown once, next to the MCP URL. Fictional data, local instance.

Client credential

Chose
A long-lived API key, exchanged for a 5-minute JWT
Instead of
The user's web session, or verifying the key on every call
Why
The key is hashed at rest and revocable. Clients can reuse the short JWT instead of paying for a hash check per request, and revoking the key also kills the JWTs issued from it.

Key lookup

Chose
A salted hash plus the key's first 12 characters
Instead of
The hash alone
Why
A salted hash cannot be looked up by value. Without the prefix, each call would verify against every stored key.

Web sign-in

Chose
A full-page Authorization Code redirect
Instead of
Google's popup and One Tap flow
Why
Brave's popup blocker stopped the popup, so some people couldn't sign in at all. A redirect has nothing to block, and the same flow became the generic OIDC sign-in in v0.1.0.
Serverless on AWSDoneLambda, S3/CloudFront and an RDS instance that stopped itself after two idle hours, all from one CDK app. A serverless Postgres replaced RDS in September 2026.

GoalHost a multi-user app on AWS that costs close to nothing while nobody uses it, and run the same infrastructure code on my laptop.

The infrastructure started as one CDK app in TypeScript, in five stacks: RDS Postgres; the backend as a Docker-image Lambda behind a Function URL; the ACM certificate; S3 and one CloudFront distribution for the SPA and the landing page; and the wake and auto-stop Lambdas. Migrations run inside the backend Lambda, which the deploy workflow invokes with {"migrate": true}. Locally, the same CDK code deploys into floci, a free AWS emulator. Since v0.1.0 that’s only needed to work on the AWS deployment itself.

Compute

Chose
Docker-image Lambda behind a Function URL
Instead of
ECS Fargate behind an ALB, with ElastiCache
Why
The Fargate version ran first, but an ALB and a cache node bill by the hour even with no traffic. Lambda costs nothing between requests, and Redis came out with it.

Local environment

Chose
The same CDK stacks deployed into floci
Instead of
docker-compose, or LocalStack
Why
docker-compose had drifted from the real stack. LocalStack's free edition now needs an auth token; floci doesn't.

Database network

Chose
Public RDS endpoint, SSL forced, generated master password
Instead of
Lambda in a VPC with a NAT Gateway
Why
A NAT Gateway is about $32 a month, more than the RDS instance cost while stopped most of the day. ADR-0002 recorded the trade-off; ADR-0009 retired it along with RDS.

Wake page (landing site)

  • health check first — goes straight to the app if the backend already answers
  • otherwise — POSTs to the wake Lambda and polls until the app is up (about 2 minutes)
then

Wake Lambda

  • starts RDS — and stamps wake-last-triggered in SSM
  • 60-minute cooldown — repeat clicks while waking are no-ops
then

Backend Lambda

  • every cold start — refreshes the same SSM timestamp
then

Auto-stop Lambda

  • every 30 minutes — stops RDS once the timestamp is over two hours old
  • DLQ and error alarm — a failed stop would silently keep the database billing
Self-hosting and open sourceDonev0.1.0 on 27 September 2026: one Docker image, SQLite or Postgres, no sign-in or any OIDC provider, under the AGPL-3.0.

GoalMake FastSpec something a stranger can try with one command and read the code of, without a Google Cloud project, an AWS account or a Postgres server.

The root Dockerfile builds the SPA, installs a pinned Spectral CLI and serves everything on port 8080. In production, CloudFront sends /specs to S3 and /api, /auth and /mcp to the Lambda; frontdoor.py does the same routing inside the app, so sign-in behaves the same in both. With no configuration, the container runs in single-user mode on SQLite, applies its migrations and generates its JWT secret into /data. Each release publishes it for amd64 and arm64.

The same release made the editor worth trying on a real spec: YAML editing (specs are still stored as JSON), import by dropping, choosing or pasting a file, download as YAML or JSON, a Petstore example on the first visit, and Swagger UI bundled instead of loaded from a CDN. Before publishing, ruff and ESLint went from about 300 and 1,500 findings to none, enforced in CI, and the backend’s dependencies were pinned.

FastSpec code view showing the Petstore example spec as YAML, with a YAML/JSON switch, Live Preview and Validate buttons above the Monaco editor.
The Petstore example in the code view, switchable between YAML and JSON.

Sign-in

Chose
AUTH_MODE=none, or any OpenID Connect provider
Instead of
Google only, or built-in passwords
Why
Nobody should need a Google Cloud project to try it. One OIDC code path covers Keycloak, Authentik, Okta, Entra, GitLab and Google; passwords would mean storing them, resets and brute-force protection.

Database

Chose
SQLite by default, Postgres when DATABASE_URL is set
Instead of
Postgres only
Why
One docker run becomes a complete install, and a backup is one file. The cost: every migration has to run on both, which CI checks.

License

Chose
AGPL-3.0
Instead of
MIT
Why
While the hosted version exists, it stops anyone from running a closed, modified copy as a service. Relaxing a license later is easy; tightening it is not.

Git history

Chose
Kept, scrubbed, in a new repository
Instead of
Publishing it as is, or one squashed commit
Why
git filter-repo replaced the AWS account ID, hosted-zone ID, certificate ARN and author email, and blame survived. A new repository, because the old pull requests pinned the old commits.
Near-zero hosting costDoneNeon's free plan instead of RDS: an idle month costs about $0.03, and the first request after 5 idle minutes waits under a second.

GoalBring the hosted version's idle month from about $17 down to cents, without a multi-minute wake-up.

A stopped RDS instance still cost about $17 a month. RDS bills the provisioned disk (100 GB, the CDK default) and backups while stopped, and AWS restarts a stopped instance after seven days anyway. Waking it took one to three minutes.

The backend now takes any Postgres as a connection string from SSM. The hosted version uses Neon’s free plan in AWS Singapore: it scales to zero after 5 idle minutes and resumes on the next connection in under a second, so there is nothing left to wake. The data and wake stacks, the wake page and the “waking up” screen were deleted, and moving the domain’s DNS to Cloudflare, where the parent domain already lived, removed FastSpec’s Route 53 zone.

v0.3.0 then added an email on every first sign-in, through an SNS topic, and cut the backend’s log retention to 30 days, since sign-in logs can hold email addresses.

Database

Chose
Neon's free plan, a serverless Postgres
Instead of
RDS, stopped when idle and woken on demand
Why
Over its limits the free plan pauses the database or blocks writes; it never bills. The data now lives outside AWS, but moving is a pg_dump and one SSM parameter away.

Free-plan limits

Chose
A banner in the app and a daily usage check
Instead of
Generic 'database unavailable' errors
Why
Neon sends no warning. The backend recognises its quota errors and answers 503 or 507 with a plain explanation, and a workflow fails above 80% storage so GitHub emails me.

Sign-up email

Chose
An SNS topic, subscribed by hand
Instead of
A subscription in the CDK stack
Why
The address would land in the public template and the deploy workflow's cdk diff output. Self-hosted instances leave the topic unset and send nothing.

Tech stack

Languages

  • Python

    The backend, the MCP server and a small CLI that migrates and serves, or moves single-user data to a signed-in account.

Frameworks

  • FastAPI

    Specs, versions, lint and auth routers, split into routers, services and repositories. In the Docker image, the MCP server and the built SPA sit behind the same app, routed by a small front door.

Topics

  • SQLAlchemy + Alembic

    ORM and migrations, written to run on both SQLite and Postgres. They run on container start, or inside the backend Lambda on deploy.

  • PostgreSQL

    For teams through docker-compose, or any managed Postgres passed as DATABASE_URL. The hosted version runs on Neon.

  • Neon

    Serverless Postgres for the hosted version, on the free plan in AWS Singapore (0.5 GB, 100 compute-hours a month). It scales to zero after 5 idle minutes, resumes in under a second, and pauses rather than bills when over its limits.

  • SQLite

    The zero-configuration default in the Docker image: one file under /data, with foreign keys, WAL and a busy timeout turned on.

  • OpenID Connect

    Authorization Code with PKCE against any provider that publishes discovery metadata. Google is just one issuer URL.

  • Spectral

    The OpenAPI linter, pinned to 6.16.3 in both images and run per request against a generated ruleset file.

  • FastMCP

    Eleven tools to read, create, version, compare, validate and lint specs, each gated by the API key's actions. Stateless, one handler per request.

  • Vue 3 + PrimeVue

    The single-page editor, with Pinia for auth state and composables holding the form editor's logic.

  • Monaco + Swagger UI

    The YAML or JSON code view and the live preview, both over the same spec object as the form. Swagger UI is bundled, not loaded from a CDN.

  • Docker

    One image for linux/amd64 and linux/arm64 on GHCR, serving the app, API and MCP server on one port.

  • AWS Lambda

    The backend as a Docker-image Lambda behind a Function URL, adapted with Mangum; secrets fetched from SSM at cold start.

  • S3 + CloudFront

    One distribution routing to the SPA bucket, the landing-page bucket and the Lambda.

  • AWS CDK

    Three TypeScript stacks (backend Lambda, certificate, frontend), covered by 51 assertion tests and deployable into the floci emulator with the same code.

  • GitHub Actions

    Tests on SQLite and Postgres, smoke tests of both images, gitleaks, releases to GHCR, the AWS deploy and a daily database usage check.

  • pytest + Vitest + Jest

    Backend, frontend and infra suites of 248, 352 and 51 tests. Five backend tests need a real Postgres, which CI provides.

Future improvements

  • The diff ignores parameters. It compares summaries and request and response schemas, so a new query parameter doesn’t show up as a change.
  • Lint pays a Node cold start per call. An HTTP sidecar transport exists in spectral_client.py with no server behind it yet, and results aren’t cached by spec and ruleset hash.
  • YAML comments don’t survive a save. Specs are stored as JSON, so keeping them means storing the raw text and reworking versions and diff.
  • The hosted app connects as the database owner. The least-privilege fastspec_app role exists as a migration, but it only runs when FASTSPEC_APP_DB_PASSWORD is set, and the Neon deployment doesn’t set it.
  • The hosted database keeps 6 hours of history. Neon’s free plan has no long-term backup, so anything worth keeping has to be exported.
  • One OIDC provider at a time, and no GitHub sign-in. GitHub doesn’t support OIDC for user sign-in, so it would need its own OAuth2 provider.