How does Swagger work?

[Ryan Allen]

I realize this is the epitome of a rookie question.
I've read over the Swagger.io website, checked out the editor and UI components, and read through the spec, but it's all very, very high level.  If I want to start using Swagger to describe my API, what do I need to set up?

Questions like these are bothering me:
How do I set up an instance of the Swagger editor?
How do I set up an instance of the Swagger UI?
Where do I need to keep my Swagger JSON files so that I can use the editor to modify them and the UI to view them?

-Ryan

[Ron]

Hi Ryan,

First, welcome to Swagger!

As a general point - you have two main ways to document your API:

1. Swagger-Editor - which you can use to document APIs before they are implemented.
2. Framework integration - depending on your development language, there are various implementations you can use to integrate the documentation as part of your code (https://github.com/swagger-api/swagger-spec#additional-libraries).

You can also choose to use the editor if you do not wish to add additional code to your application.

Each project has its own information on how to set it up:

• swagger-editor - https://github.com/swagger-api/swagger-editor#running-locally
• swagger-ui - https://github.com/swagger-api/swagger-ui#how-to-use-it

For swagger-editor, you can also use the online version at http://editor.swagger.io.

As for where to keep the Swagger JSON files, that's entirely up to you. You would eventually need to serve the file somehow (using a server). There's an option to include the spec in the UI itself, but then you won't be able to modify it directly with the editor and would have to manage it manually.

--
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.

[Tom Johnson]

I need a little more help to get started. Using the online Swagger editor (http://editor.swagger.io/#/edit), I see how I can create a YAML or JSON file that follows the Swagger spec. And I can export that YAML or JSON file. But where do I put the YAML or JSON file in order to generate my own Swagger output?

What I'm trying to do is generate a set of files that looks like the Swagger demo. I'm not trying to integrate the spec directly into my API code, but rather describe my API using the spec. 

Looking at this post https://groups.google.com/forum/#!topic/swagger-swaggersocket/-bbgbw38_fE, I see that I am perhaps supposed to use the swagger-codegen project (https://github.com/swagger-api/swagger-codegen/tree/develop_2.0) to accomplish this. I cloned the codegen project and tried to build it using this:

./bin/java-petstore.sh

I got this error: 

Please set scalaVersion := "" in build.sbt and run ./sbt assembly

That effort dead-ended with the error. (I'm really lost here among all the Swagger tools and projects.)

I wanted a beginning to end Hello World tutorial. I thought I found one here: https://github.com/swagger-api/swagger-spec/wiki/Hello-World-Sample

I get the part that explains how to run the spec file to build the Swagger output.

It says, 

Fire up whichever web server you favor, and serve the two static files. For ease of use, we've provided you with the sample files here.
Once you have your web server up and running, go ahead and clone Swagger-UI. Follow the directions there on how to run it, and direct it at your api-docs file.

I have Swagger-UI cloned. And according to Swagger-UI's project page, you build like this:

1. npm install
2. npm run-script build
3. You should see the distribution under the dist folder. Open ./dist/index.html to launch Swagger UI in a browser 

I got that working, but it just show the Pet Store demo, since I haven't integrated any new json or yaml file in there. I can't seem to find where such a json or yaml file would go. 

Can you help me figure this out? I just want to plug my own yaml or json (generated from the online swagger editor) into something and build a swagger output.

Thanks,

Tom

[Ron]

Hi Tom,

Swagger is the specification, where you create a document that describes your API.

The various tools serve various goals.

The codegen is used (mostly) to generate code from such a spec file. I believe this is not what you're currently after.

The Hello World tutorial uses Swagger 1.2 and is not update to the new Swagger 2.0 (which the editor produces).

The Editor does allow you to work with YAML for a more human-friendly editing, but the spec itself is in JSON. Swagger-UI consumes the JSON variant only.

You do not need to build the UI, unless you make any changes to it. If you clone the repository, you have a pre-compiled /dist directory you can use.

By default it opens the petstore, but you can easily modify the index.html to point to any URL.

As for serving your own specification - normally, swagger-ui takes in a URL (as mentioned above) from which it reads the spec.

You can host it locally using whichever web server you're comfortable with, and just point the UI there.

The alternative way is to use the spec parameter for the SwaggerUi object, which basically means you can assign the spec (it's a JSON object) to a variable, and pass it in as a parameter. More information on that can be found here - https://github.com/swagger-api/swagger-ui#swaggerui.

--

[Tom Johnson]

Ron, thanks for providing answers to my questions. Your responses are clear and helpful. I opened the index.html file inside the dist folder and replaced the URL to the petstore with this:

http://idratherbewriting.com/petz.json

This json file is slightly modified (petz instead of pets) from the sample minimal file from the swagger editor online. 

However, when I try to go to the dist folder on my localhost, I get this message:

"Can't read from server. It may not have the appropriate access-control-origin settings."

For that petz.json file, I made the file permissions 777. Is there something else I need to do to make it readable? 

Also, is this the simplest way to use Swagger? I'm just trying to create a very simple demo from a tech writer point of view.

Thanks,

Tom

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

408-540-8562
blog: idratherbewriting.com
twitter: tomjohnson

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/zOOIyeOnPQ4/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron]

The simplest way would be to add the spec variable in the index.html.

What you experience now is a CORS issue. More information about it - https://github.com/swagger-api/swagger-ui#cors-support (apologies for neglecting it in the previous response).

In short, in order for Swagger-UI to work, the server exposing the spec needs to have CORS enabled, at least for the URL of the spec itself.
If you want the UI to be able to operate the API itself, then CORS needs to be enabled there as well.

The only case where CORS is not required is when the UI is hosted in the same server (that is host+port) as the spec/API itself.

Instead of tweaking the server to enable CORS (for now), you can use online CORS proxy servers such as http://www.corsproxy.com/ (wouldn't recommend relying on those for production purposes).

By the way, by standard, the spec file should be called swagger.json, though of course it can be anything.

[Tom Johnson]

Thanks Ron. I uploaded the dist folder to the same server and the CORS issued went away, as you noted. 

http://idratherbewriting.com/swagger/dist/

So it works for me now. 

Thanks so much for your help.

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

408-540-8562
blog: idratherbewriting.com
twitter: tomjohnson

[Ron]

Glad to hear it worked out. Feel free to ask anything else.

[Tom Johnson]

I have some other basic questions about Swagger. Please correct me where I'm wrong. 

Swagger is a spec for writing code comments for REST.  You can write the Swagger comments in your API source code directly (e.g., Java, Python, etc.), and if you do, you have to rely on one of the Swagger implementations for that specific code base. If you don't want to write comments directly in your API source files, you can create a separate JSON file that describes everything (which is the example you were helping me with).

Which is more common with Swagger implementations -- to write comments in the API source, or to keep them in a separate JSON file?

Regardless of the way you implement Swagger, whether through source code comments or a separate JSON file, you can generate dynamic responses based on the values that users input. 

This is where I'm most confused. When I click the Try It Out button on my mock Swagger demo here: http://idratherbewriting.com/swagger/dist/, it actually tries to do something and gets a list of all kinds of links on my site. What is Swagger doing when I click that Try It Out button?

Thanks,

Tom

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

408-540-8562
blog: idratherbewriting.com
twitter: tomjohnson

[Ron]

Looks like you're preparing a nice blog post.

Both statements you provided (regardless of the questions) are inaccurate.

Swagger is not a spec for writing code comments for REST. Swagger is a spec for documenting REST APIs. Writing it manually, using code comments, actual code (some implementations do that), use code introspection (yes, that exists as well) - those are all just methods of generating a Swagger spec document. The spec itself is not concerned with the method of generation, and gives no directions one way or another.

By the second statement, regarding the 'dynamic responses', I assume you mean Swagger-UI. Again, this is not 'swagger', but a tool called Swagger-UI. The tool does two main things - displays the spec in a human-friendly form (for developers, testers, architects, technical writers and any other human consumer type of the API) and allows you to execute the API, in effect testing the API itself. The new version of the UI offers a few more features, like running validation of the spec, but all-in-all, those are the two main goals of it. This is not part of the Swagger specification, it is a support tool created around the spec. In a very broad comparison, a Swagger specification file to Swagger UI is like HTML to a Web Browser (again, very roughly).

Beyond providing the specification, it's important for us to provide a set of tools around it to for a better ecosystem. The editor (which is new in 2.0) provides you of a more convenient way to write the spec manually, the ui for display, the codegen for client/server generation (and more actually), language/library specific implementations (most of which are community contributions, which is pretty amazing) and a few other tools (with a few additional ones planned). All that to help in documenting the API, automate the work around it and generally ease the work of the people who deal with the APIs, both as producers and consumers.

Now, for your questions.

Which is more common with Swagger implementations -- to write comments in the API source, or to keep them in a separate JSON file?

I honestly don't know. They mostly serve a different purpose. Writing the spec manually is an approach normally used when you want to design the API before it exists. It gives you a clear view of the end result. Then you can either use the codegen to generate the server automatically, or give it to the developers for reference.

If you have an existing API, it may be easier to integrate a library to generate the spec for you. Many libraries do at least partial introspection, and so the documentation stays up-to-date even if the code changes.

Two things to consider - some people prefer not to integrate another library to generate the docs at runtime, and fall back to writing the spec manually. That's a reasonable use case and not unheard of. The other thing, which we'd normally recommend, is that if you have an existing API, you may prefer to integrate a library in it, if only to avoid documentation rot. We all know that code changes all the time, and documents not so much. This is why even if you use the editor to plan and design the API, once you have it up and running, you'd probably prefer to keep it coming from the code.

This is where I'm most confused. When I click the Try It Out button on my mock Swagger demo here: http://idratherbewriting.com/swagger/dist/, it actually tries to do something and gets a list of all kinds of links on my site. What is Swagger doing when I click that Try It Out button?

Swagger-UI pretty much tries to run the operation. You defined a call GET API call that executes http://idratherbewriting.com:80/petz (with no parameters), and that's what it's trying to call. If you try opening that URL yourself, your'll get your customized 404 HTML page, which is what you see in the response of the operation in the UI.

I hope this clarifies things a bit better.

[Amanda Lee]

Hi, Ron, for the Swagger specification, I have used the annotation and make it work. Swagger UI is showing my REST APIs. But how did this work? Swagger scan the resources with these annotation, and generate the Swagger specification, then Swagger UI consume the json from the url, and show it properly? Is there a json file generated here? If I want to store the json file in local, can Swagger UI consume this static file? 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.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/zOOIyeOnPQ4/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

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

--
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.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/zOOIyeOnPQ4/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

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

--
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.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/zOOIyeOnPQ4/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

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

--
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.

[Ron Ratovsky]

Hi Amanda,

Did you get a reply yesterday about it on IRC?

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
-----------------------------------------

[Amanda Lee]

Hi, Ron, yeah, I learned more about Swagger on IRC. Originally I'm using annotation via Swagger, and it works fine. But I'm trying to work on versioning via Swagger, it seems that using annotation didn't support versioning(Please correct me if I'm wrong). So I'm learning how to do versioning via Swagger in other way. As Tony indicated, we can use the API filtering to add version info into the header, I'm doing research on how to implement it. So if you have any sample for Swagger versioning, please tell me, I would like to learn how it's implemented. Thanks.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.