I'm building docs in the same repo as the API, what should I use?

If the docs live in the same repo as the API, the best choice depends on whether you want:

• API reference docs generated from code/contracts, or
• human-written product/docs site content

A practical default is:

Best general setup

• OpenAPI for the API spec
• Redoc or Swagger UI to render the reference docs
• MkDocs or Docusaurus for broader docs site content

If you want the simplest path

Use OpenAPI + Swagger UI.

Good when:

• you want docs tightly coupled to the API
• you need interactive “try it out” docs
• you want minimal setup

If you want polished API reference docs

Use OpenAPI + Redoc.

Good when:

• you want cleaner, more readable reference docs
• docs are mainly for developers consuming the API
• you care more about presentation than “try it out”

If you want a full docs website

Use Docusaurus or MkDocs alongside your API repo.

Good when:

• you need guides, tutorials, architecture notes, changelogs
• docs are more than just endpoint reference
• you want Markdown-based content in the repo

My recommendation

For most teams:

• OpenAPI as the source of truth
• Redoc or Swagger UI for API reference
• MkDocs/Docusaurus for supporting docs

If you tell me your stack (language/framework) and whether you want static docs, interactive API docs, or both, I can suggest the best exact toolchain.