redoc VS tsdoc

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.

If you want to see how Redoc will render your OpenAPI definition you can try it out online at https://redocly.github.io/redoc/.

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.

For what it’s worth, there’s also TSDoc[1] which is TypeScript’s sorta-equivalent spiritual successor, and notably uses the same format as JSDoc. Inline type annotation is great—and I vastly prefer it to JSDoc as a type annotation mechanism—but supporting the breadth of documentation capability in an inline code position would probably be unwieldy no matter how you try to accommodate it.

1: https://tsdoc.org/

Nope, they look the same, at a glance, but they're not the same. JSDoc and TSDoc are different standards, developed by different teams.

JSDoc is a terrible standard. I would rather go for TypeScript + TSDoc, then use TypDoc to generate the actual documentation based on TS typings. Alternatively, you can go for Vue Styleguidist. It's an excellent tool, but, opposite to TSDoc it's not a standard, it's just a tool.

Awesome, thank you! Would you be willing to support TSDoc ?

Clients get in-editor API documentation. Comments in your .proto files become TSDoc comments in the generated code that will show inline documentation in supported editors.

TSDoc - Looks promising but is still in early development, and lacks many examples

The raw JSDoc comments (for example, /** sum adds two numbers */) are parsed with tsdoc and rendered with custom React components.

I use tsdoc