Hacker News new | ask | show | jobs
by amne 1019 days ago
This needs a button to import an OpenAPI spec (2.0, 3.0, doesn't matter) and let the user go wild on his own APIs.

I've never thought of an API exploration tool to be a marketplace of ready-baked API collections.

The speed is there, the UI can be improved, the selling point is "wooosh" on me.
2 comments
ShadowBanThis01 1019 days ago
Yes. The OpenAPI ecosystem is in a shockingly shambolic state. I was charged with creating an API for my company's line of network-enabled products, so I defined it in OAS 3.1.

But years after the ratification of this standard, pretty much no tools fully support it, and the code-generation toolchain is a pathetic joke. When I explored it further, I found that this state was well-known in the development community, and that even mentioning an attempt to use the OpenAPI tools was a professional liability... as in nobody who knows WTF they're doing would use this shit.

The best OpenAPI-definition tool I found was Stoplight Studio, which never supported OAS 3.1 and has since been pulled from the "market." They have a Github repo that claims to be the app, but contains none of the source and is only... the documentation? I called them out on it and got only an attitude, and the repo is still up and claiming to be the whole tool. Assholes.

link
amne 1019 days ago
Yes, the tooling around OpenAPI spec is not great.

However we've worked around it. We write most of our spec by hand. We thought it would be horrible but it's not.

All our APIs accept and respond with JSON so the OpenAPI payloads are pretty much JSON schemas which means we can parse and load them up in our functional tests and automate the schema validation as part of a functional test suite. We catch a lot of unintended changes to API contract with this approach (customer is now customer_id because serializer decided so and stuff like that).

link
ushakov 1019 days ago
You can also use your OpenAPI spec to generate tests for the API

eg. with Step CI (https://stepci.com): https://docs.stepci.com/import/openapi.html

link
Volbohel 1018 days ago
Will follow up tomorrow! Our initial product had import OpenAPI schema, but we temporarily removed it after finding a few bugs.
link