GitBook doesn't handle API reference docs well

Yeah, that’s a common complaint.

GitBook is great for polished, readable docs and general knowledge bases, but it tends to be weaker for API reference documentation because it’s not really optimized for:

• Large generated references from OpenAPI/Swagger
• Nested endpoint structures with lots of parameters/responses
• Keeping reference docs in sync with a source spec
• Code-first workflows where docs are generated from annotations/comments
• Interactive API exploration like try-it-out consoles

If your main need is API reference docs, better options are often:

• Stoplight — strong OpenAPI support and design-first workflow
• Redoc / Redocly — excellent API reference rendering
• Swagger UI — straightforward and widely used
• Mintlify — good-looking docs with better API doc support than GitBook in many cases
• Docusaurus + OpenAPI plugins — more flexible if you want full control

A common pattern is:

• Use GitBook for conceptual docs, guides, onboarding
• Use Redocly / Stoplight / Swagger UI for the actual API reference

If you want, I can help you compare GitBook against the best alternative for your specific setup:

• OpenAPI-first
• code-first
• developer portal
• internal docs
• customer-facing docs