simple command line client to generate swagger doc locally

[eloui...@gmail.com]

Hello. I would like to use Swagger for our upcoming project, but have hit a few hurdles that I am not sure how to surmount.

Background: my plan is to publish the docs via GitHub pages. I am a technical writer, not a developer.

1. Can't find a simple command-line client to just run against the flat file that contains the API information documented as per the Swagger specification. Is there not some little tool that I can run from the command line and I give it the location of the JSON specification, perhaps some other parameters, and it spits out the Swagger documentation? I can then paste the Swagger documentation into an HTML file. I had assumed that such a thing would exist, yet I cannot find this thing that I guess that I had merely imagined. It seems now that it may not exist. Do I have write an application just to generate the Swagger documentation? Please advise.

2. We will ultimately want to have on our web page that contains the Swagger output a couple of fields that feed into the Swagger, so that it will be able to make the calls against the API. These fields would vary per API developer and they would be 1) the base path to the API, and 2) the OAuth 2 key. Does the Swagger documentation generator possess the capability of automatically generating the Javascript necessary to make this happen? Please inform how does this work. It would be just like Postman. I have seen other people have this in their Swagger docs, but it is not obvious to me at this time how they achieved it.

Thank you so much for your help.

Very Best Regards,

Emily

[Ron]

Hi Emily,

I'd like to clarify something about the terminology. The Swagger specification generated either manually or from your application(the json itself) is the swagger documentation. The various tools that display it in a more human-friendly manner are just presentation layers of it.

It's a good thing you mentioned you're going to public the docs via GitHub pages as that may prove to be an issue. GitHub pages does not support CORS and when serving the swagger specification file, that may prove to be a problem as it is required by some of the tools that would want to consume it.

1. You can generate static html files using https://github.com/wordnik/swagger-codegen#generating-static-api-documentation. This will not include the `Try it out` buttons. If you need that, then you should look into swagger-ui.
2. The static pages option using the codegen do not include javascript as they are completely static. Swagger-ui contains the necessary code to support what's required.

BR,

Ron

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[eloui...@gmail.com]

Hi Ron,

Thank you for the clarification. I agree it is better to keep the terminology straight. So then, let me rephrase. I am looking for a tool that will be able to take as an input the Swagger documentation and output the more human-friendly presentation of it that I have seen in many websites such as the Petstore example site. I do want the Try it out button so it seems like the swagger-ui tool is my best bet. 

I have forked the swagger-ui tool into my own repo but have not yet been able to run the swagger-ui tool. All that I can see as to how to run it is some instructions to load an object and then some sample javascript code. So then, I need to find someone who knows javascript to get it going? I guess I could talk to some people here, but was hoping for a command line utility.

I did not know this about the CORS. You say some tools may have issues. Is swagger-ui such a tool? In other words, if I use swagger-ui, will there be CORS issues? 

We do want the active docs and I have seen some GitHub Pages with the swagger in them. So it seems possible.

Thank you for your help, much appreciated.

Best Regards,

Emily

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[eloui...@gmail.com]

Here are a couple of links from people that have done it:
http://energyos.github.io/OpenESPI-GreenButton-API-Documentation/API/#!/ApplicationInformation
http://kinlane.github.io/dev-hub/api.html (this guy apparently is having issues with some browsers so that is an obstacle)

Thanks!

Emily

[Ron]

swagger-ui is a set of html/css/javascript files that give you the product you see at the pet store. Running it is as simple as opening the index.html file from your /dist directory.

You can of course customize the ui just like in the samples you shared, that is entirely up to you.

CORS is required for tools like swagger-ui. CORS needs to be enabled if the tool and the specification files are not hosted at the same web server.

In the examples above, swagger-ui is hosted as part of the github pages, so that's not an issue.
It would be an issue though for someone using swagger-ui on their own machine and trying to open your specification from there.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[eloui...@gmail.com]

Hi Ron,

OK thanks. Is there a way to get swagger-ui to generate an index.html based on a JSON file? In other words, can I feed my Swagger documentation (the swagger.json file) into swagger-ui and have it generate a UI based on my JSON? So that when I opened index.html (or whatever file), it would look like my API instead of the petstore. 

Or are you saying that I would need to manually edit the index.html file to achieve this?

Thanks so much for your help and this additional information about the CORS stuff. It sounds like if I fork the swagger-ui into the github repo that generates my GitHub pages, it will not have a CORS issue. That's good news, thanks!

Emily

[eloui...@gmail.com]

Never mind, someone here has helped me get it going. Thanks for your help in any case, appreciate it. Best Regards,

Emily

[Anoop Rajanna]

Hi Emily/Ron

Could either of you please answer the thread's last question, I have the same question.
Pasting it again.

Is there a way to get swagger-ui to generate an index.html based on a JSON file?

In other words, can I feed my Swagger documentation (the swagger.json file) into swagger-ui and have it generate a UI based on my JSON? So that when I opened index.html, it would look like my API instead of the petstore. 

Or are you saying that I would need to manually edit the index.html file to achieve this?

Thanks a ton,
Anoop

[Ron Ratovsky]

Not sure I follow your question. How would you feed the JSON to it if not by modifying the index.html? You can pass the url parameter to it, but that would be to a hosted json. Otherwise, you'll have to edit the index.html.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Anoop]

Hi Ron,

Sorry if I was unclear with my previous question.

Currently I have generated a static html page using the swagger codegen as you have mentioned earlier (which does not have the "try it out" feature/button).
I manually generated the swagger.json using the swagger editor online and used the following command to generate the static html page

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i ~/Downloads/swagger.json -l html -o samples/

Since I am not familiar with html, css, javascript etc. I wanted to know if there is a way to generate the swagger UI (like petstore UI) by using my own swagger.json (meaning is there a cli or command that I can feed my swagger.json and get the UI)
 If so, how would I do that, could you please elaborate if possible.

Appreciate your help

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Ron Ratovsky]

Aha, now it's clearer, thanks.

So swagger-ui is not a statically generated html set but rather a static set of html pages that dynamically load a swagger definition and renders it. This is very different from the codegen that indeed reads the swagger.json and just pours it all into an html file without having any of the swagger.json info left in it.

So if you want to use swagger-ui itself, you'd have to use a slightly different approach. If you need assistance with how to use swagger-ui, let me know.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[catchaag]

Hi Ron,

I want to use swagger-ui to generate html documentation which can be hosted online for our consumers to read.

Could you please eloborate how can i use swagger-ui tool to generate html pages using my swagger.json files.

Thanks

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.