Hi, am looking into the best way to spec out, document, built and test an API these days.
It seems that these days the general idea is to use RAML for designing, then convert to OAS for documentation/implementation/testing, given the communication around the people behind RAML joining the OAS initiative last year, correct?
I realy like RAML for designing, as the API we’re designing has a lot of similarities between endpoints for which RAML seems to be the best fit to keep things DRY.
However, RAML 1.0 was releases in April 2017, I cannot find any reference to a version 1.x or 2.0 (no new branch in the GitHub repo for example) and I’ve concluded that there is a mismatch to what RAML 1.0 offers and what OAS 2.0 offers.
OAS 2.0 has properties like readOnly and writeOnly, which are tied to the HTTP Methods and allow you to have a single type definition for the payload/body of get/put/post’s, while differentiating the differences in payload between those HTTP Methods, thus sticking to the DRY principle. RAML doesn’t support those properties natively. You can use Annotations for just put it into your RAML documents, but none of the existing convertors will act upon those annoations. There seems to have been some effort in trying to make annotations more usefull to this respect, but that initiative seems pretty dead as well: https://github.com/raml-org/raml-annotations/pull/2. (also see RAML 1.0 data types, required properties and GET, PUT, POST, https://github.com/raml-org/raml-spec/issues/610)
So I’m wondering what the state of RAML is. Is a new version in the works that will align RAML better with OAS? Are there plans to keep keep releases of RAML and OAS in sync, so that RAM can be used icw with the latest version of OAS without loosing/missing out on stuff?
If I complely missed some info about the ongoing efforts on RAML, I’m sorry, please correct me