[_fat_santa]

General question. I currently have a Node API that I am the solo dev on and am considering bringing up to OpenAPI spec to get nice docs and stuff. Wanted to ask others here, for a solo dev would it be worth it? Or is that sort of thing really geared for teams where multiple people are using and integrating the API?

[ljm]

The output will only really be as good as what you describe, really, and if you’re only using it for yourself it might feel like overkill, particularly if you want the spec as the source of truth and have to rewrite your API to fit a generated interface.

It may have more use to you if your API is quite large or re-uses a lot of components (e.g if you follow something like the JSON:API spec), because you can generate boilerplate from it then.

Can also be useful if there’s another team consuming the API, so you can design new endpoints and figure out the requirements before getting to work. That spec can then be used to generate mock servers or used for e2e testing.

[disintegrator]

You might like zod-openapi (https://github.com/samchungy/zod-openapi). You write Zod schemas which, on their own, are a great way to define a validation and de/serialization layer in your API and you then can additionally use them to generate an OpenAPI doc.

[Swizec]

OpenAPI is only useful if you intend for your project to become bigger than what fits in your head or if you intend to keep a project alive for long enough to start forgetting things you did a while back.

[jlengrand]

Or if you deliver an API and any of your users / customers want to use anything else than a raw API. IMHO the top value of OpenAPI isn't for you, it's for the people who will use what you make

[salomonk_mur]

Agreed. Most of the value comes when people other than you need (or will need) to use it.