redoc VS spectral

Link: Redoc

OpenAPI is great, we use it in combination with redoc (https://github.com/Redocly/redoc) to have a almost 0 effort API for our product.

But man, my tokenizer is in trouble with OpenAPI and OpenAI.

Redoc: Generate API documentation

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

The output and in particular the LLM content seems distracting and unhelpful to me.

In their example[1], three paragraphs start with "Oh boy" and "Oh dear". There are also "whopping 272 invalid schema examples" (twice), "whopping 334 rate limit responses", and a recommendation to "add rate limiting to a whopping 173 operations".

The prompts[2] contain "You like chatting in a playful, and a somewhat snarky manner.", "Keep the tone casual and playful, and a bit snarky.", so this seems partly intentional.

Still, LLM seems unnecessary to me here and I'd prefer a version without that. So, Spectral[3] I guess.

[1]: https://ratemyopenapi.com/report/31bae2fb-bda1-471b-8c1d-142...

[2]: https://github.com/zuplo/rate-my-openapi/blob/0fcef3702592d8...

[3]: https://github.com/stoplightio/spectral

I recently started playing with Spectral for validating OpenAPI & AsyncAPI specifications against a common set of rules.

In this post, I show how to use Spectral to check if only lowercase alphanumeric characters are used in the keys of OpenAPI paths.

You can also use linters such as Stoplight's spectral to make sure the API specification is looking good.

Spectral

Would you count API Linting? I use spectral for maintaining API standards on our application: https://github.com/stoplightio/spectral