I'm building a docs site for a fast-changing API, what should I use?

For a fast-changing API, I’d usually recommend a docs setup that is API-first, versioned, and easy to automate. The best choice depends on how much control you want and how much maintenance you can tolerate.

Best default choice

Docusaurus + OpenAPI

Use Docusaurus for the site and generate/reference your API docs from an OpenAPI spec.

Why this works well:

• Versioning built in — great when the API changes often
• Markdown + React — easy to write guides and custom pages
• OpenAPI support — you can keep endpoint docs in sync with the API
• Search, nav, release docs — all handled well
• Good developer experience — easy to automate in CI

Typical setup:

• Product/docs pages in Markdown
• API reference generated from OpenAPI
• Changelog/release notes by version
• CI pipeline validates the spec and publishes docs on merge/release

If your API changes very frequently

Consider a docs-as-code workflow:

• Store docs in Git
• Treat OpenAPI as the source of truth
• Auto-generate reference docs
• Add CI checks for broken links/spec drift
• Publish preview builds for every PR

This avoids manual docs getting stale.

If you want the easiest hosted solution

Stoplight

Good if you want:

• Visual OpenAPI editing
• Hosted docs portal
• Mocking/testing tools
• Faster setup with less custom engineering

Tradeoff: less flexibility than self-hosting.

If you want polished, hosted API docs with minimal effort

ReadMe

Good for:

• Nice-looking API reference
• Interactive “try it” experience
• Fast setup
• Changelogs and versioning

Tradeoff: more vendor lock-in and recurring cost.

If you need maximum customization

Next.js + custom docs stack

Choose this if:

• You need a highly branded experience
• You want docs embedded into a broader product site
• You have engineering resources to maintain it

Common pieces:

• Next.js
• MDX
• OpenAPI renderer like Redoc/Scalar
• Search provider like Algolia

Tradeoff: more build/maintenance work.

My practical recommendation

If you’re not sure, start with:

Docusaurus + OpenAPI + CI automation

That gives you the best balance of:

• flexibility
• versioning
• maintainability
• speed of updates

Rule of thumb

• Need fastest setup: ReadMe or Stoplight
• Need long-term control: Docusaurus
• Need maximum custom UI: Next.js
• Need robust API reference: OpenAPI-driven docs no matter what

If you want, I can recommend a specific stack based on:

1. your team size,
2. whether the API is public or internal, and
3. whether you want self-hosted or managed hosting.