Stop Renting Your OpenAPI Docs

OpenAPI is the most rented open standard in software.

The spec was designed for portability. The whole point of OpenAPI is that any tool can read it, that the schema lives in your repo as YAML or JSON, that nothing about the format itself ties you to a particular vendor. The format succeeded at that goal in a way few open standards do. Every API tool reads OpenAPI. Every doc renderer supports it. The portability is real.

Most teams then hand the rendering of their portable spec to a vendor that charges $99 to $300 a month for the privilege of putting a CSS skin on a format that already belongs to them.

What the field gives you

Swagger UI is free, owned, and visually frozen in the year SmartBear took it over. The .NET 9 team dropped Swashbuckle as a default dependency in 2024, which is the closest the industry has come to a public admission that the renderer has aged out of relevance.

Scalar is open source and modern. It reads OpenAPI cleanly, ships fast, and looks like it was designed in this decade. It is also a single-purpose renderer; if a project also needs guides, recipes, architecture notes, a changelog, and an llms.txt, Scalar is the API tab, not the docs site.

Mintlify, Redocly, Stoplight, ReadMe, and Bump.sh sell beautiful OpenAPI rendering on a subscription. Mintlify Pro is $300 a month. ReadMe starts at $99. The output is gorgeous and the surrounding template language is proprietary; exporting to a standard format loses the components the vendor renders. You are paying for a CSS skin on a format you already own, and you are paying forever, because the migration cost of leaving rises with every page of documentation you write.

The remaining option is to build the chain yourself: Docusaurus plus a redoc plugin, or Hugo plus shortcodes, or a custom Astro site. This works for teams with spare frontend engineers willing to maintain a bespoke documentation pipeline. Most teams do not have spare frontend engineers willing to maintain a bespoke documentation pipeline.

None of these give a project owned, beautiful, and multi-source from the same build.

What you actually want

You wrote your OpenAPI spec because it was portable. You did not write it to migrate it into Mintlify’s MDX dialect.

What fits is a renderer that reads the OpenAPI spec directly, produces a beautiful API reference from it, and puts that reference inside the project’s docs site alongside the rest of the documentation: guides, recipes, architecture notes, changelog, MCP schemas if the project ships them, llms.txt and llms-full.txt for the agents grounding their next API call on what your spec says.

One source of truth. One renderer. One site. The OpenAPI tab sits beside the guides; the guides sit beside the changelog; the changelog sits beside the agent-readable surfaces. All produced from the same build, on the project’s URL.

How

Sourcey reads OpenAPI directly. The config is one block:

{
  tab: "API",
  slug: "api",
  openapi: {
    spec: "./openapi.yaml",
    index: "rich",
  },
}

That produces one API tab generated from the spec, with operation pages, schema anchors, examples, search entries, sitemap entries, and agent-readable output, sitting alongside whatever else the project ships from the same renderer.

The pipeline reads the spec where it lives, without converting it to MDX or any other vendor template language, and without creating a migration cost the next time the project changes rendering strategy. The source of truth stays what it always was: the OpenAPI YAML in the repo.

Cheesestore, in public

Cheesestore is the live OpenAPI showcase. A clean API-first project rendered from a single OpenAPI spec. The reference pages, the schema, the operation details, the examples: all generated from one YAML through the same Sourcey renderer that handles C++ source for Icey and Go packages for Scafld.

Cheesestore is not interesting for the API itself. It is interesting because the rendering chain is two pieces, an OpenAPI spec and a renderer, with no docs platform between them, no template language wrapping the operations, and no monthly fee on the build.

What this means

A project with an OpenAPI spec already has the source of truth a modern API docs site is built from. There is no migration to a vendor’s dialect required, no separate site for “API docs” and another for “guides”, no template language to learn before the team can ship.

The migration is not a rewrite. It is a config change.

The OpenAPI spec stays in the repo where it always was. The renderer stops being something the project rents. The reference pages become part of a docs site the project owns, indexed for both human search and agent grounding, designed at the bar the field has set.

Documentation belongs to the project.