
Ask HN: OpenAPI (v3), API Blueprint, RAML – what do you like and why? - asdkhadsj
I&#x27;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&#x27;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&#x27;t just a popularity contest.<p>So - if you have an opinion on the matter, what do you use and why?
======
shoo

      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.

