esh-b / raml-to-swagger-converter

A java project to convert RAML 0.8 definition to Swagger 2.0 definition

RAML-to-Swagger-Converter

About the project

This repository contains a java project that converts RAML v0.8 API definition to Swagger v2.0 definition. It contains a standalone application for such conversion and also support using the converter as a library within your project. For more info on swagger definitions, Click here. For RAML docs, Click here

Steps to run the utility

• Download and install Apache Maven (https://maven.apache.org)
• In the project directory issue mvn package which will build the application in the raml2swagger-app/target folder
• Run the application with java - jar target/raml2swagger-{version}-jar-with-dependencies.jar <input file>
• An example is provided in the example directory which will convert jukebox-api.raml (RAML 0.8) to jukebox-api.json (Swagger 2.0).

Steps to use the project as a library

• Download and install Apache Maven (https://maven.apache.org)
• In the project directory issue mvn install which will build the application and library
• Add the dependency into your POM or use the built library in your project. The library JAR is in raml2swagger-lib/target.

Todos

• This project currently supports only conversion of RAML v0.8 (RAML 1.0 parser library is not yet available for java as of now). The support for RAML 1.0 conversion to Swagger 2.0 has to be made once RAML 1.0 parser is available.
• Almost all the edge cases (rarely used definition fields in API definition) are taken care of. But incase something is missed out, please raise an issue.

Footnotes

• Incase you find any bugs or want to add any new feature that's included in the Swagger definition (say, in the future), then you are highly welcome to contribute to the project.

raml-to-swagger-converter's Issues

Failing to convert example json referenced in RAML

Hi,

I tried run the utility against the Example "jukebox-api.raml" . When executing I am getting the following exception
org.codehaus.jettison.json.JSONException: A JSONObject text must begin with '{' at character 1 of jukebox-include-album-songs.sample at org.codehaus.jettison.json.JSONTokener.syntaxError(JSONTokener.java:463) at org.codehaus.jettison.json.JSONObject.<init>(JSONObject.java:206) at org.codehaus.jettison.json.JSONObject.<init>(JSONObject.java:313) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.getResponseInfo(RAMLtoSwagger.java:648) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.getMethodsDescription(RAMLtoSwagger.java:493) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.getSpecificResourceData(RAMLtoSwagger.java:455) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.retMethodsData(RAMLtoSwagger.java:425) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.retMethodsData(RAMLtoSwagger.java:438) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.retMethodsData(RAMLtoSwagger.java:438) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.getResources(RAMLtoSwagger.java:338) at org.macrulez.utils.raml2swagger.RAMLtoSwagger.convertToSwagger(RAMLtoSwagger.java:393) at org.macrulez.utils.raml2swagger.App.run(App.java:60) at org.macrulez.utils.raml2swagger.App.main(App.java:36)

The JSON content within "jukebox-include-album-songs.sample" looks to be valid but still the converter is failing to identify it as an valid JSON.

Could you please help in resolving this issue.

Regards
Arun

How to Convert the entire RAML folder to swagger

I have a RAML file which reads the schemas and responses from different folders. I want to convert this entire folder to swagger. When I convert the RAML file alone, the descriptions and the responses are missing. Any help would be appreciated. Thanks.

YAML to RAML support

Hi There,
Do you know if this repo supports conversion of YAML (2.0) to RAML (0.8).

RAML 1.0 Support

There is already a parser for RAML 1.0

https://github.com/raml-org/raml-java-parser/releases/tag/1.0.16

How are the plans to include this in the converter?