Ask HN: OpenAPI (v3), API Blueprint, RAML – what do you like and why?

5 ポイント投稿者 asdkhadsj7 年前1 コメント

I'm evaluating OpenAPI, Blueprint and RAML for primarily API documentation but code generation might be neat too. While there are lots of comparisons out there, I'm also curious on the pulse of usage - ie among this crowd, which is most used? Most used often means most tooling support and etc, so this isn't just a popularity contest.

So - if you have an opinion on the matter, what do you use and why?

1 コメント

shoo7 年前

  1. OpenAPI
       - more popular, more tooling
       - spec is partially defined by
         references to other specs,
         so you have to read at least
         three specs in parallel to
         understand it.
  2. API Blueprint
       - never heard of it
  3. RAML
       - less popular. unlike OpenAPI,
         you can reference external
         JSON schema documents to define
         types

I use OpenAPI (fka Swagger) as there's lots of it already in use at the the company I work at. I need to consume APIs produced by other teams, and those teams publish APIs using OpenAPI, so that's the end of the decision process.

I have had a reasonably positive experience using oas-raml-converter to mash OpenAPI specs into RAML, to use as an input to RAML-based tooling.

The more I look at all these ways of defining and structuring APIs, the more something like gRPC sounds like a good idea, but that may just be a "grass is greener" reaction, i've never worked on a serious project that's used gRPC or similar for integrating systems.