Very cool, lot of potential. I wonder how it would work in an interconnected environment where multiple services are needed to properly call an endpoint. For example if you need to request with a particular type of jwt to get a response from a user's perspective.
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.
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.
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).
This hurts. I've been using Hapi professionally for 5 years now, and it is a joi (hehe) to work with. Modules in the hapi ecosystem, ie boom, joi, and lab, are baked into my servers from top to bottom.
Much thanks to the devs that made this possible over the years. It is a shining example of what a JavaScript tool should be like. I wish it could be given the money and time it deserves.
fwiw, I've been doing professional JS (mostly server, good amount of client) for about 5 years now and have never pulled in a single function package before as a direct dependency. Every team I've been on has used Lodash or Underscore in the capacity you describe.
I agree that this is the sane alternative, but sanity does not seem to be winning out. Our friend number-is-nan, for example, has 12 million downloads a week.
It’s like someone saw how much the is-odd/is-even (yes one of those first two depends on the other and just returns the inverse with !) packages are downloaded per week and said “hold my beer”
Of course they don’t hold a candle to “is-number” which has 29M/week
Of course this is completely unrepresentative of reality because “yolo just install dependencies at deployment” may mean it’s downloaded 5 or 10 or 50 times for a high traffic site/service with a bunch of backend installations.
It actually sounds like they're saying it's definitely feasible and encouraging people to build the right product. Their comment from 7 months ago indicates this is something that's obviously important to them.
Dealt with something similar at my old company. If you have the option to go page by page, this may work for you. The original site was in ColdFusion, and we slowly reimplemented it in AngularJS (around 2014.) We used an NGINX whitelist that had all route permutations that needed to go to the AngularJS site send it to that container, and everything else went to the ColdFusion environment. Over time, the major components of the site was converted to Angular and the users were none the wiser (besides noticing that the average load time had decreased by THIRTEEN SECONDS, no I am not kidding.)
The same pattern at my current role has worked while migrating an AngularJS app to Vue.
I've had that happen before when visiting some music news sites in iOS safari. Seemed like some sort of malevolent cookie, as it started when I would go to a particular site and persisted until I cleared browser data.
