Problem: why isn't my API displayed? Metaproblem: how to debug API definitions?

[Jonathan Sachs]

I'm just beginning to use Swagger, and I'm trying to create my own resource definition and API declaration. They're not working, and I need some help figuring out why.

When I load Swagger it displays the message "200 : OK http://localhost/swagger-ui/dist?api_key=special-key." In other words, "I found the resource definition at http://localhost/swagger-ui/dist, and everything is OK." But everything is not OK; the resource definition refers to an API declaration, and Swagger doesn't display it. Nor does it tell me why not.

I've found that I can make any sort of change to the resource definition, even introducing JSON syntax errors, without affecting Swagger's response. I can even rename the file to something other than api-docs.json so that Swagger can't find it. The only way I can to make Swagger say something other than a "OK" is to enter a URL in the Swagger heading that refers to a non-existent file or directory. Then I get a message that says "Can't read Swagger JSON from..." (But if the URL refers to a directory that exists but doesn't contain an api-docs.json file, I get "OK.")

Here's what my resource file looks like. (I've changed some of the values to conceal possibly confidential information.) It's in the document space's /swagger-ui/dist directory. An API declaration file named xyz.json is in the same directory.

{
   apiVersion: "0.1",
   swaggerVersion: "1.1",
   basePath: "localhost/swagger-ui/dist",
   apis: [
      {
         path: "/xyz.{format}",
         description: "Prototype xyz API"
      }
   ]
}

That's the problem.

The metaproblem is that I don't see any way to diagnose the problem, short of "debugging" the JavaScript code. My customary approach to this type of problem is to start with the distributed example, which presumably works, and look for a significant difference in my own non-functioning case. If I can't find one, my fallback strategy is to transform the distributed example into what need a little at a time. If it breaks at some point, I have a good idea where the problem is; if it doesn't, I've completed my task even if I haven't figured out what originally made my code fail to work.

But here there is no distributed example; the example is on the Wordnix server where I can't examine it directly.

[tony tam]

Hi Jonathan, there are a number of things that can go wrong with something like this, especially when building it from scratch.  The most solid, tested way is to begin with a sample application--one that has been built by those who are familiar with the framework, has tests, and is supported.  That said, I'd suggest you start with any number of samples from here:

https://github.com/wordnik/swagger-core/tree/master/samples

In that sample folder, there is an example called "no-server" which allows you to run a lightweight HTTP server (jetty) and serve up the documentation directly from it.  Everything will work, in fact, you can even make API calls and get responses, since the swagger definition tells it to route requests to our sample petstore server.

I don't know if that's the answer you were looking for but that's the right way to start with swagger.

[Jonathan Sachs]

Thank you, Tony. A sample is exactly what I wanted. Unfortunately I'm having a rocky time getting one.

I have (again) two problems.

The first is that github for Windows, the git client I installed, has stopped working. When I try to clone any of the repositories on my local disk, it says it failed to clone the repository and suggests that I check my internet connection. My internet connection works fine, as this message demonstrates. It's not clear what else might be wrong. The hints I've found on the Web are either intended for a case where github never worked, or they appear to refer to some other version of github than the one I have.

The second problem is that it's not clear which of these "samples" really are samples. I expected a sample to be a minimal directory structure containing a resource listing and a few API specifications, with instructions that say in effect, "put these things in the directory where your Swagger instance is set to look them." Instead, the samples I examined have very elaborate directory structures that suggest they are whole projects. I can't get a good look at them until I can clone them, but at least some appear to be complete Swagger installations for use with various languages, without any resource listing or API specification files that I can find. In other words, they duplicate what I've got without providing what I need.

I hope you can clarify what's in these repositories and how they're intended to be used. Perhaps, as a bonus, you can even suggest what might have gone wrong with github!

[tony tam]

Hi Jonathan, I don't know what could have gone wrong with your github client, but I do know you can download directly from github, without cloning:

https://github.com/wordnik/swagger-core/releases/swagger-project_2.9.1-1.3.0-RC1

As for getting started, you have lots of options.  You can read the wiki, which is a tutorial for getting going:

https://github.com/wordnik/swagger-core/wiki/java-jax-rs

Or you can follow along with the samples.  Since configuring different server integrations is a job onto itself, most folks have been quite content starting with a working sample.  If you aren't familiar with that, you can certainly read the wiki.  But as we all know, code moves faster than documentation.

Tony

[Jonathan Sachs]

Thank you again. I downloaded the samples you suggested and found the one that matches my needs (no-server). By copying that into document root I was able to get the sample to work.

I added the file I created for my own API to the resource listing. Now it appears as a heading on the page, and when I click it I get a list of the resources in the API.

When I click any one of the resources, however, I get nothing. No description of the resource; no indications of what is wrong.

What tools are available for diagnosing the problem(s)?

[tony tam]

Typically when manually creating the json files, you have to use browser-debugging tools (i.e. chrome developer tools) to troubleshoot the issue.

There is an open ticket in swagger-ui to create a javascript-based validator:

https://github.com/wordnik/swagger-ui/issues/135

And you can also use swagger-codegen to do validation as well:

https://github.com/wordnik/swagger-codegen#validating-your-swagger-spec

The codegen tool is fairly heavyweight so you might want to wait for #135 in swagger ui.

[JimB]

I'm going to go out on a limb and say you have an extra comma.  (At least that's my most common problem.)

Swagger will choke with the slightest syntaxual issue with the JSON input.  I suggest pasting your JSON code into a validator program like jsonlint.com.  This will help you to find those pesky little syntax issues.

[Robert Crooks]

Was just going to point out that there are many other JSON validators out there to check that part:

• Online: http://jsonlint.com
  
• Desktop: many JSON editors do; my favorite on Mac is https://itunes.apple.com/us/app/power-json-editor/id499768540?mt=12
  

Don't know what's available on Windows, but I'm sure there are some.