How to Convert the entire RAML folder to swagger

Question

How to Convert the entire RAML folder to swagger

srionem opened this issue 7 years ago · 14 comments

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.

Answer 1 · 2017-11-22T17:09:46.000Z

The app should be able to convert with all inclusions. Can you please show a snippet of your raml and perhaps describe your directory layout.

Answer 2 · 2017-11-27T11:10:14.000Z

I have the same issue here. This is what I did:

Created maven project (let's say under D:\Workspace\raml-sample)
I've copied the jukebox-api sample project with all included files. (all files from: https://github.com/raml-org/raml-examples/tree/master/others/tutorial-jukebox-api) to D:\Workspace\raml-sample\src\main\raml\
I used springmvc-raml-plugin to generate the code --> this works fine
Now I want to genrate swagger from the same project
3.a I've cloned your project into D:\Workspace\RAML-to-Swagger-Converter
3.b Built the project successfully with mvn package
3.c Went to the folder D:\Workspace\RAML-to-Swagger-Converter\raml2swagger-app, and tried generating the swagger with the following command
java -jar target/raml2swagger-app-1.1-SNAPSHOT-jar-with-dependencies.jar D:\Workspace\raml-sample\src\main\raml\jukebox-api.raml

I get the following exception:

10:45:11.553 [main] INFO  org.macrulez.utils.raml2swagger.App - Converting D:\Workspace\raml-sample\src\main\raml\jukebox-api.raml...
Exception in thread "main" java.lang.RuntimeException: Builder not found for <NodeTuple keyNode=<org.yaml.snakeyaml.nodes.ScalarNode (tag=tag:yaml.org,2002:str, value=todes.MappingNode (tag=tag:yaml.org,2002:map, values={ key=<org.yaml.snakeyaml.nodes.ScalarNode (tag=tag:yaml.org,2002:str, value=song)>; value=<NodeTuple keyNode=<org.y:yaml.org,2002:str, value=song)>; valueNode=<org.yaml.snakeyaml.nodes.ScalarNode (tag=!include, value=./jukebox-include-song.schema)>> }{ key=<org.yaml.snakeyaml.nodes.value=artist)>; value=<NodeTuple keyNode=<org.yaml.snakeyaml.nodes.ScalarNode (tag=tag:yaml.org,2002:str, value=artist)>; valueNode=<org.yaml.snakeyaml.nodes.ScalarNode-artist.schema)>> }{ key=<org.yaml.snakeyaml.nodes.ScalarNode (tag=tag:yaml.org,2002:str, value=album)>; value=<NodeTuple keyNode=<org.yaml.snakeyaml.nodes.ScalarNode (>; valueNode=<org.yaml.snakeyaml.nodes.ScalarNode (tag=!include, value=./jukebox-include-album.schema)>> })>>
        at org.raml.parser.builder.DefaultTupleBuilder.getBuilderForTuple(DefaultTupleBuilder.java:79)
        at org.raml.parser.visitor.YamlDocumentBuilder.onTupleStart(YamlDocumentBuilder.java:351)
        at org.raml.parser.visitor.NodeVisitor.doVisitMappingNode(NodeVisitor.java:141)
        at org.raml.parser.visitor.NodeVisitor.visitDocument(NodeVisitor.java:233)
        at org.raml.parser.visitor.YamlDocumentBuilder.build(YamlDocumentBuilder.java:100)
        at org.raml.parser.visitor.YamlDocumentBuilder.build(YamlDocumentBuilder.java:183)
        at org.macrulez.utils.raml2swagger.RAMLtoSwagger.convertToSwagger(RAMLtoSwagger.java:377)
        at org.macrulez.utils.raml2swagger.App.run(App.java:60)
        at org.macrulez.utils.raml2swagger.App.main(App.java:36)

I problem might be the version of RAML used in the example. I've used 1.0 which is not supported yet. But is this the exception that I would get in this case? Because I think here the included file was not found.

Answer 3 · 2017-11-27T12:47:38.000Z

@GhaTMA Did you try running the jukebox API example from our Example dir? That uses RAML 0.8. The RAML project examples (link that you shared) were recently updated to RAML 1.0. So, checking for the Jukebox API example in our project can help to identify whether the RAML version is causing the issue.

Answer 4 · 2017-11-27T12:58:36.000Z

I ran the following command:

java -jar target/raml2swagger-app-1.1-SNAPSHOT-jar-with-dependencies.jar D:\Workspace\github\RAML-to-Swagger-Converter\Example\jukebox-api.raml

and got a slightly different exception:

13:56:10.766 [main] INFO  org.macrulez.utils.raml2swagger.App - Converting D:\Workspace\github\RAML-to-Swagger-Converter\Example\jukebox-api.raml...
Exception in thread "main" java.lang.RuntimeException: resource not found: jukebox-include-song.schema
        at org.raml.parser.visitor.YamlDocumentBuilder.onCustomTagError(YamlDocumentBuilder.java:391)
        at org.raml.parser.tagresolver.IncludeResolver.resolve(IncludeResolver.java:80)
        at org.raml.parser.visitor.NodeVisitor.resolveTag(NodeVisitor.java:155)
        at org.raml.parser.visitor.NodeVisitor.doVisitMappingNode(NodeVisitor.java:135)
        at org.raml.parser.visitor.NodeVisitor.visitMappingNode(NodeVisitor.java:83)
        at org.raml.parser.visitor.NodeVisitor.visit(NodeVisitor.java:242)
        at org.raml.parser.visitor.NodeVisitor.visitResolvedNode(NodeVisitor.java:173)
        at org.raml.parser.visitor.NodeVisitor.visitSequence(NodeVisitor.java:270)
        at org.raml.parser.visitor.NodeVisitor.visit(NodeVisitor.java:250)
        at org.raml.parser.visitor.NodeVisitor.visitResolvedNode(NodeVisitor.java:173)
        at org.raml.parser.visitor.NodeVisitor.doVisitMappingNode(NodeVisitor.java:143)
        at org.raml.parser.visitor.NodeVisitor.visitDocument(NodeVisitor.java:233)
        at org.raml.parser.visitor.YamlDocumentBuilder.build(YamlDocumentBuilder.java:100)
        at org.raml.parser.visitor.YamlDocumentBuilder.build(YamlDocumentBuilder.java:183)
        at org.macrulez.utils.raml2swagger.RAMLtoSwagger.convertToSwagger(RAMLtoSwagger.java:377)
        at org.macrulez.utils.raml2swagger.App.run(App.java:60)
        at org.macrulez.utils.raml2swagger.App.main(App.java:36)

I think here the problem is clearly with the includes.

Answer 5 · 2017-11-27T13:41:31.000Z

@sslb can you please look into this issue? The code seems to throw exceptions for our own API example. It would be better if you can recheck the code that you pushed recently.

Answer 6 · 2017-11-27T14:16:33.000Z

Hi All, My RAML has dependecies. For example, the raml structure goes like this., The name of the folder is ramlFolder which has api.raml (the raml file), schemas folder which has schemas for several foders, examples folder which has the examples of all the apis. ramlFolder --> api.raml examples --> example-1(folder) --> example.json example-2(folder) --> example.json schemas --> schemas-1(folder) --> schemas.raml schemas-2(folder) --> schemas.raml Now, the api.raml at the top level consumes the schemas and examples from the folders. If I convert the api.raml alone, some of the dependencies are lost. Is there a way that I can convert the entire folder? Thanks

…

On Mon, Nov 27, 2017 at 8:41 AM, Eshwanth Baskaran ***@***.*** > wrote: @sslb <https://github.com/sslb> can you please look into this issue? The code seems to throw exceptions for our own API example. It would be better if you can recheck the code that you pushed recently. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#7 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AgTXiyLvoq4jfql5DqUWvKI1vP_gOlnOks5s6rwLgaJpZM4QmALw> .

Answer 7 · 2018-09-08T15:46:14.000Z

Hi,

Conversion should work with dependencies altogether. This is the scenario we are working with it as well. I am really sorry that I haven't picked this up, but the GitHub notification got buried in my mailer.

Nevertheless, inclusion do work. I'll re-check the example project as well.

Answer 8 · 2018-09-08T18:16:55.000Z

@sslb Please do it asap.

Answer 9 · 2018-09-13T13:14:10.000Z

Right, so the OP's problem is that his includes are likely relative and he invokes the converter from a directory different from where the RAML is. This is probable as he provides the full path for the RAML.

Currently the include statements are relative to the CWD if the include statements are relative. As a workaround to this, just CD into the RAML directory (where your structure is) and invoke the converter that way. It does work fine.

As for the other mentioned issue around the Jukebox example, indeed that fails as is but for an entirely different reason. Inclusion works just fine, however there seems to be syntax errors.

The sample JSON files are not valid JSON objects and Jettison complains about that.
I've committed fixes to the samples and some extra code about example handling.
The converter originally just ignored examples, but when I fixed that, the problem is now exposed.

I can no longer push fixes (no permission), therefore I won't be able to create a pull request.

@esh-b Can you please fix the repository permissions so I can create a PR? Currently it does not allow me to push up a new branch.

Answer 10 · 2018-09-13T13:24:18.000Z

As an addition perhaps we could mention in the README to run the converter in your RAML directory otherwise there's no way to find the includes. Includes by the way are resolved by the MuleSoft library we are using and they are loaded as resources. This prevents us from tinkering with the paths and try multiple options.

You do need to run the converter in the proper directory and not supply a path to the RAML. That won't work.

Answer 11 · 2018-09-13T14:52:37.000Z

@sslb Okay. You could possibly change the Readme file and other necessary commits and send me a pull request. I have created a new branch.

Answer 12 · 2018-09-13T15:56:16.000Z

I cannot push up new branches anymore, therefore I won't be able to create a PR.

Answer 13 · 2018-09-14T07:09:38.000Z

I cannot push up new branches anymore, therefore I won't be able to create a PR.

Not sure about the reason for that. Doesn't googling help?

Answer 14 · 2021-06-16T01:42:26.000Z

Still facing this issue, any ETA to fix?