I work at a rather large company that has an internal gateway for all APIs. Each api has an associated OpenAPI doc and the standardization makes it incredibly easy to peruse all capabilities across the company, despite programming language, organizational, and physical barriers between developers.

I concede that the magic there is in the standardization of API level docs, and not the special sauce that OpenAPI brings to the table. I just don't know of an alternative that is as language agnostic as OpenAPI.

Personally, I enjoy using server frameworks with first class support for OpenAPI. The projects I've used it in have forced me to write documentation first, and really think about what I'm trying to accomplish from a design perspective. I am by all metrics a very average developer, and a tool that pushes me to think in a new way is one I'd like to use.

Here's an example of the type of framework I'm talking about, this is Flask + OpenAPI. https://github.com/zalando/connexion

That said, different strokes for different folks. I am sure it is a massive headache to deal with all that YAML if you're not getting anything out of it.

How do you deal with reasonably complex data structures in OpenAPI?

We're in desperate need of an API documentation solution, and i reached for OpenAPI early on but found it (the UIs availab,e specifically) immensely confusing. It looks great when it's a small flat object, but when you're returning hundreds of unique fields and structures, lots of enums, etc - the result is an automated mess.

I don't think this is strictly a fault of the spec, but of the UI. They seem to design it around the pet shop example, which doesn't seem beneficial to any of our internal, large API responses.

Thoughts?

I tried out Stoplight Studio last year as a GUI for creating OpenAPI specs, and was pretty pleased with it:

https://stoplight.io/

I've also written a small custom JS script that generated an OpenAPI spec file by reflecting over some internal data structures, so that's an option as well, and there's lots of tools out there for generating OpenAPI specs based on code (Java annotations, Python models, etc).

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.

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.

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

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.

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/

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

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

What tools do you use?

See sibling comments for some links

Hey, I use it at work. It's really just a fairly stable way of documenting APIs. Sure you can try do fancy generation of it from one side, and generate code on the other, but treat it just as a standard way of talking about requests and responses and you'll see the benefits.

If you do want a good benefit, here's a testing engine that'll run through an OpenAPI file and confirm the server's adhering to it correctly: https://dredd.org/en/latest/

This seems, so much more valuable than trying to use OpenAPI to generate server side code. Thanks!

My two cents, Using OpenAPI enables in going API first. The stakeholders agreeing on an API is perhaps one of the most important things in lifecycle of the product and rest of the things really just snowballs from there. Also, an API that changes frequently is perhaps not a good sign, it will hurt the clients, new version of the API is different thing though.