redoc VS Hugo

ReDoc Interactive Demo

ReDoc focuses on simplicity and readability, presenting the API documentation in a user-friendly format. It supports dark mode, multiple languages, and offers a seamless browsing experience for API consumers.

There are a few other tools out there that are at least marginally better than the default Swagger UI such as ReDoc (https://github.com/Redocly/redoc).

When we redid the Mux docs (https://docs.mux.com/api-reference) we actually just decided to build our own renderer. It really wasn't as bad as you might think, at build time we pull in the JSON version of our OAS spec and render it as a static build in our Nextjs app. Don't get me wrong, it wasn't trivial, but the benefit of having complete control over the output has been well worth it.

Redoc: http://localhost:8080/redoc

ReDoc is a tool that's similar to Swagger UI. It also takes an OAS and renders an interactive HTML page with full API documentation details; however, it has a notable difference.

take a look

Redoc is an open source tool to generate API reference documentation websites from OpenAPI definitions.

FastAPI for Python has an awesome way of doing this. It comes with two choices: Swagger and Redoc, the former being more interactive while the latter is (IMO) more visually appealing. I'm sure you could implement one of these using Spring.

Starlite has substantially enhanced OpenAPI (3.1) documentation - in fact, its the most complete autogenerated schema around, and it ships with Redoc, Swagger-UI and Stoplight-Elements static sites.

This blog is running on Hugo. It had previously been running on Jekyll. Both these SSGs ship with the ability to create excerpts from your markdown content in 1 line or thereabouts.

Hugo

Hugo is a popular static site generator specifically designed to create websites and documentation lightning-fast. Its minimalist approach, emphasis on speed, and ease of use have made it popular among developers, technical writers, and anybody looking to construct high-quality websites without the complexity of typical CMS platforms.

As per many other comments, it sounds like a static site generator like Hugo (https://gohugo.io/) or Jekyll (https://jekyllrb.com/), hosted on GitHub Pages (https://pages.github.com/) or GitLab Pages (https://about.gitlab.com/stages-devops-lifecycle/pages/), would be a good match. If you set up GitHub Actions or GitLab CI/CD to do the build and deploy (see e.g. https://gohugo.io/hosting-and-deployment/hosting-on-github/), your normal workflow will simply be to edit markdown and do a git push to make your changes live. There are a number of pre-built themes (e.g. https://themes.gohugo.io/) you can use, and these are realtively straightforward to tweak to your requirements.

Create the technical documentation of your project You can use any of the following options: * A wiki, like the ArchWiki that uses MediaWiki * Read the Docs, used by projects like Setuptools. Check Awesome Read the Docs for more examples. * Create a website * Create a blog, like the documentation of Blowfish, a theme for Hugo.

Doing this made me appreciate existing SSGs like Hugo and Next.js even more👏👏

I suggest hugo: https://gohugo.io/

Generates a completely static website from MD (and other formats) files; also handles themes (including a lot of them rendering well on mobile), and different types of content - posts, articles, etc. - depending on the theme.

It's open source and, being completely static, cheap as fuck to self host.

I would suggest looking into static site generators. Some popular examples, which are used myself are: - Hugo: https://gohugo.io/ - Jekyll: https://jekyllrb.com