I'm building a developer experience for external APIs, what should I use for docs?

For external APIs, the best default is usually:

OpenAPI for the API contract + a docs site generator on top of it.

Recommended stack

• Spec: OpenAPI 3.1
• Docs renderer: Redoc, Scalar, or Swagger UI
• Docs site: Docusaurus, Mintlify, or GitBook if you want a full docs portal
• Examples: real request/response examples generated from your spec and SDKs

Why this is the usual best choice

• Machine-readable source of truth for endpoints, auth, schemas, errors, pagination, etc.
• Easy to keep in sync with code and SDKs
• Good for external developers because they can:
  • read docs
  • try endpoints
  • generate clients
  • validate requests
• Supports multiple outputs from one spec:
  • reference docs
  • interactive “try it” UI
  • SDK generation
  • mock servers
  • changelogs / diffs

What I’d pick by stage

If you’re early-stage

Use:

• OpenAPI
• Redoc or Scalar
• Markdown guides for onboarding, auth, webhooks, rate limits

This gives you solid API reference docs without too much process overhead.

If you want a polished developer portal

Use:

• OpenAPI
• Docusaurus or Mintlify
• Redoc/Scalar embedded or linked
• Tutorials, changelog, auth guide, troubleshooting

This is good when docs are part reference, part product.

If you want maximum “developer experience”

Add:

• API Explorer / “Run in browser”
• Code samples in multiple languages
• Postman collection
• SDKs
• Status page + changelog
• Examples for common use cases
• Webhook docs with event payload examples

Tooling suggestions

Best all-around docs rendering

• Redoc: clean, strong for reference docs
• Scalar: modern, interactive, good UX
• Swagger UI: familiar, but less polished for external-facing portals

Best docs portal / content site

• Mintlify: strong for modern API docs, fast to ship
• Docusaurus: flexible, open source, great for full docs sites
• GitBook: easy collaboration, less control

What matters more than the tool

For external APIs, the docs should include:

• Quickstart
• Authentication
• Base URLs / environments
• Rate limits
• Pagination
• Errors and error codes
• Idempotency
• Webhooks
• Versioning and deprecations
• Code examples
• Sandbox/testing instructions

My practical recommendation

If you want one answer:

Use OpenAPI 3.1 as the source of truth, render it with Redoc or Scalar, and wrap it in Mintlify or Docusaurus if you need a full developer portal.

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

1. your team size,
2. how much you want to maintain,
3. whether you need SDK generation,
4. and whether your API is REST, GraphQL, or gRPC.