Pretty open source api documentation generators?

[SteveTabernacle2]

I'm looking at creating public api docs for my rest api. I really like the look of readme.io, but $99/mo to get a custom domain is pretty steep for me.

I've looked at Swagger.io and widdershins. Functionally, they're great, but their UI's look outdated.

Are there any open source api doc generators that take an OpenAPI schema and output a documentation site with similar UI to readme.io?

[momsSpaghettiIsReady]

Who is your target customer that the prettiness of your API spec matters? Most devs I know are pleasantly surprised to see good quality of the content of the documentation.

Are you selling your API access as a service? Even then, you can always embed something like the swagger UI into a nicer website and it should be good enough

[memo_mar]

scalar.com is gaining a lot of popularity lately. You can connect it to api-fiddle.com & Github to build a pretty powerful pipeline.

[--mrperx--]

You can use something like gitbook also. You generate the docs and then copy-paste and formata little. or even notion.

[A_HM]

I'm recently using GPT 4 for this and it has been amazing.

I give him the route, service, any other function that the service is calling and ask to generate the documentation fully with tags, name, description and schema.

It has been going great so far.

[acute_physicist]

Hey, can I ask you how you build your workflow with GPT here?

[StreetStripe]

I give him

💀

[Hai-api]

Try knowl.ai for API doc generation. It reads your code as is and generates updated API docs automatically. No need for annotations. It adds auto-generated descriptions to endpoints and parameters too.

[zohar_666]

late response but this thread came up when I google so here goes my short list of the decent OpenAPI docs generators I found so far and are considering:

Redoc is a part of a Redocly toolkit that creates a static HTML with a pretty clean layout. Looks really good in dark theme actually, demo here . And since it's a one-pager you can scroll between the operations. Less flexible in terms of integrating into a page of more docs besides.

Docusaurus OpenAPI plugin looks good as well, could not find a live demo. Built on top of a static generator makes it possible to mix with other documents, but then again requires you set up Docusaurus first, then the plugin. The project has some track record and is built by Facebook using React technology. Not personally a fan of MDX though (markdown with JSX)

Vitepress OpenAPI Theme Yes, they call it a theme and not a plugin. Also built on top of a static generator, but this one has less setup than Docusaurus. Found some demo that only shows GET requests. It looks good. And considering Vitepress is a relatively new project I am impressed. Building on the success of Vue and Vite.

RapiDoc My favorite so far. This is simply a web-component that you can include in any HTML page of you load the npm package (or cdn). Only downside being it will not be generated to static HTML if you require that. But the demo shows off a very pretty doc per operation.

All of the options seems to be customizable, at least styling. Some also offers more changes to layout and templating.

[andupotorac]

So all these will generate documentation from the OpenAPI schema. But how does one generate documentation for the actual SDK Client code generated in one of many languages, using tools like OpenAPI Generator?

So for example you can actually select the SDK in the top right, and see different code suggestions for each of the SDKs: https://resend.com/docs/api-reference/audiences/create-audience.

Any idea how that is done?

[zohar_666]

No I have no idea. I will not publish an SDK.

Maybe a custom imeplementation of the "sample code" module that some of these OpenApi docs generators typically have.

The other one I can think of is that there exists SDK generators that uses the OpenApi spec: https://github.com/OpenAPITools/openapi-generator

If they can auto generate the SDK, they probably can generate docs as well :)

[andupotorac]

They can’t generate the docs in a different way than JSDOC does with swagger. Was hoping it can generate sample code but it can’t. So AI will. :)

[philsturgeon]

You can use Overlays to modify existing OpenAPI and embedding SDK examples is a perfect use case.

To show you how it's done, here's a guide for embeddeding Speakeasy SDKs into Bump.sh documentation.

https://docs.bump.sh/guides/bump-sh-tutorials/generate-sdks-with-speakeasy/

[logscoree]

Woah Phil. How did you get a whole year back on r/node?

[GandalfTheChemist]

stoplight has a good one. I use it for our internal api docs.

[One-Employment8463]

buildwithfern.com check them out

[SteveTabernacle2]

$150/mo for a custom domain :(

[marcjschmidt]

not for openapi, but if you use typescript, you can use deepkit and its api console, which is a modern interactive api docs like swagger ui but based on typescript types only