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.
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.
Confused why this is posted now - the project has been dead for years it seems..
because of HN's algorithm, it's a social network after all.
evidence that people vote without reading (sufficiently)?
exactly
It is really just noise: I do not blame the poster (which probably did not realize) but who is supposed to help the algorithm
GitHub repo is marked as archived by the owner. Is this project still alive?
The company behind it got bought by Oracle, so all the public stuff was archived. Not sure if there is still any community around it after that.
I may have missed it, but wondering what the advantages are over OpenAPI/Swagger?
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.
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...
Looks to be an abandoned project based on the last Github update being 3 years ago.
See also Microsoft's TypeSpec: https://typespec.io/ and https://learn.microsoft.com/en-us/azure/developer/typespec/o...
It's actively developed and used to spec Azure services, see https://azure.github.io/typespec-azure/ and all of the public Azure service specifications at https://github.com/Azure/azure-rest-api-specs (they're all OpenAPI for consistency, but newer development happens in TypeSpec, and the OpenAPI is an output).
It’s interesting (and of course understandable) how all the effort goes into specifying RMM level 2 but not level 3 APIs.
[dead]