Re:Ask HN: Is OpenAPI Documentation Superior?
by hirokib on Thursday March 25, 2021 @05:30PM
(#26585649)
So there is an intuitive aspect that brings comfort? I think that's super important. Especially in healthcare where most APIs/dev experience is terrible, making someone feel at home seems really important.
Re:Ask HN: Is OpenAPI Documentation Superior?
by bigiain on Thursday March 25, 2021 @08:49PM
(#26587625)
Not so much “intuitive“, much closer to “familiar”. I don’t expect an API doc tool (or any useful/powerful dev tool) to be zero learning curve, but I don’t want my team climbing 2 or 3 different learning curves unnecessarily.
But yeah, totally right on the “feeling at home” idea.
Mostly familiarity.
The OpenAPI spec and the Swagger tools are something that a _lot_ of devs are familiar with, and they integrate well with lots of other tools (We have OpenAPI docs embedded in out Confluence/Jira workflow).
That SlateDocs looks nice, but I've never heard of it before.
If I had two browser tabs open to evaluate different 3rd party APIs to consume, I'd somewhat strongly lean towards the one that used OpenAPI, because I know it'd fit in with our existing toolset and experience.