undefined | Better HN

0 pointsadkadskhj5y ago0 comments

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?

0 comments

acemarke5y ago

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).

j / k navigate · click thread line to collapse