Replace abandoned spectacle-docs with a modern OpenAPI renderer

Open
#69 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Quiet
Tech stack
javascript, openapi, scss
Domain
build-system, documentation

Research direction

Start with gulpfile.js, doc_template/, and the current dist/swagger.yaml generation flow, including the custom Handlebars views, SCSS files, and JavaScript. Prototype Redoc in dist-redoc/ alongside the existing output, then compare the rendered documentation and branding before recommending whether to replace the current renderer.

Written by the indexing model from the issue text.

Description

Context

API docs are generated from dist/swagger.yaml via spectacle-docs@1.0.7
(see gulpfile.js, doc_template/). Spectacle has been effectively
unmaintained since ~2019. Our setup includes non-trivial customizations:

  • Custom Handlebars views (main.hbs, partials: swagger, json-schema, layout)
  • 9 SCSS files on Foundation
  • Custom JS (main.js, traverse.js) and branded logo

Spec is ~8.6k lines and is also consumed by MCP code generation, so
OpenAPI remains the source of truth regardless of renderer choice.

Candidates

Tool License Pros Cons
Redoc (OSS) MIT Closest three-panel look to Spectacle; mature; static HTML Theming is JS config only — no template overrides
Scalar MIT Modern UI, built-in "Try it" playground, active dev Playground needs CORS on API; newer, smaller ecosystem
Stoplight Elements Apache-2.0 Embeddable web components, CSS-themable Less polished than Redoc/Scalar
Docusaurus + docusaurus-plugin-openapi-docs MIT Reference + guides/tutorials in one site; highest ceiling Highest migration effort
Mintlify / Bump.sh / ReadMe Commercial Hosted, search analytics, versioning, changelogs Subscription; vendor lock-in

Tradeoff

Deep Spectacle template tweaks don't carry over to any replacement —
expect to rebuild branding via each tool's theming API. Lowest-risk
swap is Redoc (static HTML, three-panel). Best UX upgrade is Scalar.
Best long-term platform is Docusaurus or a hosted option if we want
guides alongside reference.

Proposal

Prototype Redoc into dist-redoc/ alongside current output to eyeball
differences before committing.

Dominant language
Java
Stars
6
Forks
3
Avg merge
2h 12m
Merged PRs (30d)
1

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quire-api/quire-api

All issues in quire-api/quire-api

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.