Hacker News Reader

Comment by mechanicalpulse | Hacker News Reader

Mostly the fact that it's based on Markdown, which makes the raw specification far easier to read with a text editor than OpenAPI/Swagger. Markdown also permits styling in the various descriptive portions, which makes for superior documentation.

I ran into some deficiencies, though, at least with the parser I was using with Node/TS -- IIRC (and it's been a few years), I wasn't able to specify a wide variety of disparate responses (e.g., an HTTP 200 with an application/json Content-Type header, an HTTP 200 with a text/plain Content-Type header, and an HTTP 400 response with an X-Error-Code header). Since API Blueprint was introduced, the tooling around OpenAPI has improved dramatically and it's become a de facto standard, so I'd probably avoid API Blueprint for anything serious.

It's unfortunate, though, because I really liked the idea.

View on HN

When OpenAPI opened the polymorphism door with 'oneOf' and the like, it seems like it turned into a shitty language written in YAML rather than being a good concise way to communicate API design.

Former company enforced OpenAPI specs to be able to publish any API endpoint, devs just wanted to push code, so they made vague shit specs because it's pulling teeth to do it the right way (didn't help that the spec enforcer couldn't fully read YAML documents with references, so copypasta was rampant)...

I guess there's the endless cycle of 1) a format is created, 2) the format evolves to do more, 3) winds up being overbearing, 4) a new format is created...

I've experienced the mind-numbing frustration of API specs that don't match the implementation, which is why I have embraced the concept of requiring the spec to be part of the implementation. For example, the express-openapi package for Node.js expects the specification to be supplied as a property of the very function implementing the operation. This permits middleware to access the OpenAPI specification directly and utilize it for coercion and validation of requests and responses, so you get several birds with one stone.

I've also experienced enterprise OpenAPI deployments where the API specifications were owned by a separate enterprise API architecture team and were fed into some central consumer-facing documentation portal along with whatever unbeknownst infrastructure sat between the application and the Internet. Developers had access to the spec repository, but API architects reviewed PRs and made any recommendations for normalizing interfaces or using existing or canonical types.

Either way works, IMNSHO.

Edit: I should also say that I have likely misrepresented the deficiencies I experienced with API Blueprint. Take it with a grain of salt; I literally do not remember because it's been ... checks code ... nearly five years since I touched that project. The issue I ran into may have been as simple a problem as providing two example POST requests with slightly different payloads or two example HTTP 200 responses with slightly different response bodies. This is something that API documentation might often include to show multiple common use cases. It may have not have even been part of the actual spec or it may have been only a limitation of the specific UI renderer I was using.

> When OpenAPI opened the polymorphism door with 'oneOf' and the like

Technically this is a feature of JSON Schema, not OpenAPI. But since OpenAPI is a superset of JSON Schema...

Reply on news.ycombinator.com