Swagger and a hand-written docs site are causing too much maintenance

That’s a common pain point. If Swagger/OpenAPI plus a custom docs site are both drifting, the core issue is usually duplicated documentation sources.

A few ways to reduce maintenance:

Best options

1. Make OpenAPI the single source of truth

   • Generate Swagger UI / Redoc / docs site directly from the spec.
   • Avoid hand-editing endpoint descriptions in a separate site.

2. Generate docs from code annotations or schema

   • If your framework supports it, keep route definitions, request/response schemas, and examples in code.
   • Let the OpenAPI file be generated automatically.

3. Use a static docs generator that consumes OpenAPI

   • Tools like Redoc, Docusaurus + OpenAPI plugins, or Stoplight can render polished docs from the spec.
   • Then the “hand-written” part is only for high-level guides, not API reference pages.

4. Split docs into two layers

   • API reference: auto-generated from OpenAPI
   • Guides/tutorials: hand-written, but fewer in number and more stable

Practical recommendation

If maintenance is the issue, I’d suggest:

• Keep OpenAPI
• Replace the hand-written API reference with generated docs
• Keep only a small number of human-written pages for onboarding, examples, and workflows

If you want to simplify further

You can also:

• Remove Swagger UI from production-facing docs if it’s redundant
• Host a single docs portal that embeds generated reference + static guides
• Add CI checks so OpenAPI and code stay in sync

If you want, I can help you design a lower-maintenance docs setup based on your stack.