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 vendor. Few open standards land that cleanly, and this one did: every serious API tool and doc renderer reads 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. That works if you have frontend engineers to spare and want them maintaining a bespoke docs pipeline instead of the product. Most teams have neither the spare engineers nor the appetite.

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 reference sits next to the guides, the changelog, and the agent-readable surfaces because they all came out of the same build on the project’s URL, not because something stitched four separate products together after the fact.

How

Sourcey reads OpenAPI directly. The config is one block:

{
  tab: "API",
  slug: "api",
  source: openapi("./openapi.yaml"),
}

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.

You already own it

A project with an OpenAPI spec already has the source of truth a modern API docs site is built from. The spec is portable by design. The only thing that ever made it un-portable was choosing to render it through a vendor whose template language you cannot take with you.

So the change is the config block above and nothing else. The spec stays in the repo where it always was, the renderer stops being a line item, and the reference pages become part of a site the project owns, indexed for human search and agent grounding alike, at the bar the field set rather than the one a vendor invoices for. Cheesestore is that whole argument running in public from a single YAML file.

OpenAPI was portable the entire time. Paying rent on it was always a choice.