[smt88]

I have extensively used OpenAPI Specs for years.

You're right that tools are almost all partially-baked.

I use specs to generate data models in TypeScript, Kotlin, and .NET (for different projects). This gives me compile-time guarantees that my API docs match my code.

I also use it for generating documentation and client SDKs in other languages.

If used correctly, it can help automate hundreds or thousands of hours of error-prone work. It also forms an unbreakable contract between systems in totally different languages (not unlike what Protobufs could be used for).

It takes a few hours to find tools you like, but after that, it's generally smooth.

[acemarke]

What's your preferred tool for generating TS API clients? I tried the official `openapi-generator` tool last year, but was horrified to see that a fairly small API file resulted in 5000 lines of boilerplate TS code that was trying to provide multiple levels of overrides and abstraction for configuring the calls.

[smt88]

I don't actually generate clients. I generate data types for requests and responses, which I then use with regular HTTP clients.

I'm sure there are some client generators out there that work well and create lean code, but it's easy enough to use off-the-shelf HTTP clients with some additional type guards.

This is the tool I use most often for TypeScript: https://github.com/horiuchi/dtsgenerator

[0xffff2]

I spend weeks looking for tools that I could even us, much less like, and eventually gave up and wrote everything by hand. I would be very interested in hearing about any OpenAPI tools that you would recommend.

[smt88]

For .NET, it's best to write the spec as annotations on your controllers and request/response classes using NSwag[1].

The situation is similar in the Java world. It's better to annotate, rather than start with your own spec.

For TypeScript, I mostly use a CLI tool[2] that generates type definitions, which I then use in my routing system and controllers to make sure that any changes to paths, requests, and responses are going to cause compiler errors until they're fixed.

1. https://docs.microsoft.com/en-us/aspnet/core/tutorials/getti...

2. https://github.com/horiuchi/dtsgenerator/

[ccleve]

How do you use it for generating documentation? Can you generate anything other than Swagger UI for API docs?

[smt88]

The best CLI documentation generator I've found so far is Redoc[1].

There are tons of hosted solutions for docs (Apimatic, SwaggerHub, Stoplight, and Apicurio Studio).

My favorites are SwaggerHub[2] and Apicurio[3], because their editors are solid and they have good compatibility with all the nooks and crannies of the OpenAPI v3 spec.

1. https://github.com/Redocly/redoc

2. https://swagger.io/tools/swaggerhub

3. https://studio.apicur.io

[rolha-capoeira]

What tools do you use?

[smt88]

See sibling comments for some links