nextra
nextra copied to clipboard
shuding
Generate pages from an OpenAPI spec
It's very common to have your user guide content written in MDX, while your API Reference is an auto generated OPENAPI spec.
Many want to generate browsable web pages from the OpenAPI spec. To do this, there's a bunch of standalone tools (e.g. swagger) that can generate a site from the JSON spec.
However, this usually means your main user guide docs are separated from your API docs, with a totally different look and feel.
The Vercel Docs have a nice approach. The API reference is listed in the sidebar with all the other docs. When the user clicks into that section, it fetches the openapi spec file, and dynamically generates the API reference pages. The pages are within the same docs site and with a consistent theme. https://vercel.com/docs/rest-api/endpoints
It woul be great if nextra could support this out of the box. The user is able to configure a path to an openapi spec file - either a file inside the docs repo, or a URL to a remote file. The user can configure where the API reference should be made available, e.g. under what path, title in the nav menu. When the user clicks that link, the spec file is fetched, and the pages are dynamically generated.
This would be an immensely valuable feature for great docs.
More here https://github.com/shuding/nextra/discussions/1024
For those looking for a way to do this right now, I put something together using widdershins
It's not perfect, but some tweaking of the template files lead to a good-enough, static OpenAPI presentation.
On a separate site, I used next-swagger-doc-cli for the "live" API browser.
+1 this would be so handy . The Vercel docs look great. I haven't been able to find anything that comes close to matching Nextra's aesthetics
@B2o5T @shuding any chance you guys could take a look and share your thoughts on this idea?
@sdairs Any idea how vercel Api refs are built?
I'm particularly interested in the sub groups. I saw that redocly supports in grouping tags which is a must for us because of the APIs complexity. Redoc.ly supports it via x-tagGroups, but if there is an option implementing this as an embedded view like vercel did it would be much better.
Any help / advise is appreciated!
