|
|
|
|
|
|
by rodinia
2069 days ago
|
|
|
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. |
|
|
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?