Confused why this is posted now - the project has been dead for years it seems..
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
API Blueprint
11–16 of 16 posts
Re: API Blueprint
#12Earlier quoted context omitted.
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 dispar…
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…
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.
Re: API Blueprint
#13[dead]
Re: API Blueprint
#14Re: API Blueprint
#15See 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).
Re: API Blueprint
#16Earlier quoted context omitted.
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 dispar…
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…
> 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...