Unless I cant see quite how to do it, I think there should be a way to configure sending the api key as a proper base 64 encoded basic auth header, for those apis that work in that manner.

There was an issue similar to the one I'm having, with a few important differences, posted a while ago:
#2

My issue is essentially the same as the OP. The differences here are in our implementations.

Fehguy posted this in response to the OP's question:

------------START POST-------------
Hi, that's possible. What server did you deploy? The java version or scala one? Or did you roll your own? There was a bug in our ApiOriginFilter which caused the allow orgin to not work.

I can tell you about your last question after you tell me what language/sample app you're working with.

Tony
-------------END POST---------------

I am getting the Access-Control-Allow-Origin problem myself, let me tell you about my setup.
Currently we have a PHP API hosted on one machine, and another machine hosting Swagger-Node-Express and a Swagger-UI. Since Swagger does not currently support auto documentation for PHP APIs, I have had to create my own doc template in javascript to be hosted from the node server. I used the node server's sample files as a template and modified them from there to create the Javascript files which are exported to .json. The Swagger-UI is hitting the node server, and all of my hard-coded API doc renders correctly into the UI. The problem happens when I try to use the "Try it now!" sandbox feature of the Swagger-UI. When looking at the errors through Firebug or Chrome, I get the Access-Control-Allow-Origin error on URLs that I can GET by simply copying and pasting it in another tab. Now, I understand one problem this may be solved is by making the API return headers to Allow Access Control, but I was wondering if there is any work around to this or if this is the only solution.

Hello,

I wonder where I have to deploy the UI in order to access the API. apparently I get an Access-Control-Allow-Origin because the ports are not the same but I would rather want to host the UI over the apache and run the api on another tomcat/jetty port. Is that possible?

Javascript:
XMLHttpRequest cannot load http://localhost:8081/slc/pet/resources.json. Origin http://localhost is not allowed by Access-Control-Allow-Origin.

Also, is there any more documentation available? I can't quite figure out how the UI gets its information from the api, for example, where does this lead to:

swagger.api.basepath
http://localhost:8002/api

I mean, the UI asks for a resources.json file, but in the sample application I cannot find where path "/api" is defined and where a resources.json is returned.

Thanks for any help.
david

I feel like src/main/html/css/screen.css is generated with Sass or something like that, as I doubt a human would write all of those insane "nested" (indented) rules with hyper-specific selectors.

Are we missing the source stylesheet?

For a DELETE operation, the 'Try it out' button fails to show. Path fields don't show up either for a DELETE.

#68 (comment)

Hi there,

I'm facing a strange problem I never had before with swagger: for all my POST/PUT method, swagger is making first an OPTIONS method, and then a POST/PUT one if Allowed.

I'm not really sure I want to implement OPTIONS method, which is extremely rare.

How to avoid this?

Thanks!

After I executed 'middleman', the UI works fine. However, if I give my local resources.json (http://localhost:9000/resources.json), it stops at 'Fetching _register...' , where register is one of controller.

If I just paste these two links to browser, it returns correct JSON string.
http://localhost:9000/resources.json
http://localhost:9000/register.json

What am I missing on this UI library?

There don't seem to be any build instructions available.

I'm entirely new to haml and sass, and have no idea what other tools I might need to build this. A short build instruction would be awesome!

Including oauth2 support in the UI would be a nice to have feature

Even though no api_key is specified, the operation URL, will contain the api_key as a query parameter, such that the string "?api_key=" is appended at the end of the URL. This may not cause the operation to fail, but this is is somewhat misleading when viewing the request URL. Moreover, the master branch does not behave this way.

swagger-ui ignores the model descriptors coming in from the server. Not good. It should show em

In this issue #4, an upcoming 1.1 release is mentioned, but that was 4 months ago. Is there any work in progress? Is there a list of features that should be built? From the top of my head:

• Show more of the data in the resource description json in the UI
• Show descriptions of the models in the UI
• Allow non-GET requests from the UI

I'd like to help out, and I'm ready to fork and start making pull requests, but it would be a waste to duplicate work :)

Thanks,

Erik

The UI in overhaul branch doesn't display the value of the "notes" field of @ApiOperation. Do you plan to add that, or is this field deprecated?

I'm getting the following error trying to build

cake dist
Build distribution in ./dist

node.js:134
        throw e; // process.nextTick error, or 'error' event on first tick
        ^
TypeError: Bad argument
    at Object.mkdirSync (fs.js:360:18)
    at Object.action (/Users/arulkumaran/git/swagger-ui/Cakefile:25:10)
    at /usr/lib/node_modules/coffee-script/lib/coffee-script/cake.js:42:26
    at Object.run (/usr/lib/node_modules/coffee-script/lib/coffee-script/cake.js:67:21)
    at Object.<anonymous> (/usr/lib/node_modules/coffee-script/bin/cake:7:38)
    at Module._compile (module.js:402:26)
    at Object..js (module.js:408:10)
    at Module.load (module.js:334:31)
    at Function._load (module.js:293:12)
    at Array.<anonymous> (module.js:421:10)

Is there any plan to support nested parameters like this ?

{
  "user": {
    "name" : "John",
    "type" : "guest"
  }
}

I am not really sure how it could be shown in the ui but it would a nice feature :)

I have one more question about the naming conventions. I do not want to have ".json" or ".xml" in my URLs but when I delete it, the UI only shows "fetching..." but doesn't show the provided methods. For example,

@path("/pet.json")
@Api(value = "/pet", description = "Operations on a pet")
@singleton
@produces({"application/json"})

works, but

@path("/pet")
@Api(value = "/pet", description = "Operations on a pet")
@singleton
@produces({"application/json"})

does not work (only difference is the missing ".json" in the @path).

What are the conventions here? Can I somehow get rid of the ".json"?
Thanks a lot.

David

When entering a value for a parameter, and hitting ENTER, the whole page is submitted. It would be great if swagger-ui could catch the ENTER key pressed event, and submit the parameters for the relevant operation.

When you specify the default value for a param using the field defaultValue, the UI doesn't show the default value in the text field. Not only that, when you try the request, the default values are not sent in the request.

HTTP PATCH is naked with Swagger UI with out any style

Take a look at this picture to get a clear picture of what I mean

Ideally PATCH should get some color closer to PUT

Getting:

TypeError: 'null' is not an object (evaluating 'this.headerView.update') on swagger-ui.js:668

It looks like @options is null in SwaggerUI.coffee on line 51. I'm running a vanilla install, just cloned the repo today.

There seems to be a problem with refreshing after clicking an operation in Swagger-UI. Same applies when sending links to an operation.

For example, go to: http://petstore.swagger.wordnik.com/#!/user/createUser_post

You will see that the path is rewritten, the hash is removed which results in:

http://petstore.swagger.wordnik.com/!/user/createUser_post

Refreshing after this will result in a 404.

I'm working on an API which has a resource at “/resources.json/...”, so I have a problem as Swagger by default expects to use “/resources.json” for its resource discovery URL. I changed the resource discovery URL for this API to “/apidoc.json” but found that Swagger-UI still wouldn't work. Through trial-and-error I found that the change linked to below is the most minimal find-replace-all of “resources” with [other string] I could do to make it work, though I honestly don't understand neither the code, nor JavaScript and CoffeeScript well enough to know why this fixes the problem or what a proper fix would be (since this one is a change on the generated, rather than the source files).

Yesplan@741858c

http://petstore.swagger.wordnik.com/ doesn't include the latest commit fixing #19.

You don't have a tag for release 1.1.0. Please make tags so we can know what source version corresponds to the stable build.

Thanks...

The master doesn't contain the UI built with pull request #20 included.

I have recently written a lib called Swagger.Net to emit the spec for the new Asp.Net Web API.

There appears to be an issue with Swagger-UI in Internet Explorer that causes a redirect to the root of the site. Could be a bad route in Backbone?

I'd like to bundle up the Swagger UI as a NuGet pkg. Are there any plans to make Swagger UI work in IE for .NET community adoption?

Thanks!

Would be nice to have a stylesheet that enables nice printing of the UI.

This should have:

• all UI controls (buttons, inputs) and "try it out" functionality hidden
• all items expanded
• header removed
• page width constraints removed (fluid layout)

Looks like the existing stylesheet should be split out (since it's only for "screen" now) so relevant sections can be re-used for the printable version.

When parsing the API documentation inclusion .{format} is required for the javascript to parse the JSON.

When calling the API from the web app it would be great if that could be optionally exluded.

For some reason the .json works locally with NGINX but Web Brick on Heroku chokes on it.

Right now, if you send a datatype boolean, it is rendered as a (multi-line) textarea, which is very unintuitive.

Expect that it would be rendered as eg: a drop-down with possible values true or false, or as a checkbox.

Having a option to select "json" or "xml" format in the UI would be nice to have

Currently swagger-ui demands that GET request on the resource root should provide the operation listing

I feel this is limiting, let me explain with the following scenario

/authors.json/{id} provides specific author's details. I want /authors.json to provide list of authors (using optional parameters to filter and do pagination) instead of the operation listing

While resources.json provides the resource listing

I want to use resources.json/authors to provide the operation listing

This way api discovery wont stand in the way of the resource. I tried it and found that it is not supported by the current version of swagger-ui.

I'm the author of the Restler API framework trying to add API Discovery features using Swagger UI. I love the ui design and functionality and willing to contribute to this project as well. Pointers and support are greatly appreciated :)

I am trying to get a ruby project going with swagger - the API in question requires an API token be passed in the header.

In your examples you mark parameters as "header" but then it swagger-ui still places them in the query string - which only works for your API.

As a temp fix I am always making the token the first parameter and have make the following horrible, horrible hack to get things working; (in submitOperation of swagger-ui.js)

if (error_free) {
    var params = form.serializeArray();
    var token_name = params[0].name;
    var token_value = params[0].value;
    params.splice(0,1);
    var invocationUrl = this.operation.invocationUrl(params);
    $(".request_url", this.elementScope + "_content_sandbox_response").html(
        "<pre>" + invocationUrl + "</pre>"
    );
    $.ajax(
    {  url: invocationUrl,  dataType: 'json',  data: '{}',  success: this.showResponse, beforeSend: 
    function (xhr) {
                xhr.setRequestHeader(token_name, token_value);
            }

    }
    ).complete(this.showCompleteStatus).error(this.showErrorStatus);
}

Any thoughts on a permanent fix for this?

The "build" folder seems to be older than the latest "source" folder. I think I need the "using basePath from the apis" change done by user "ayush" from about a month ago, while the "build" folder dates from about 2 months ago. Could you please update the "build" folder?

I've been trying to support a nested under a directory, like /test/testing.json. I have the discovery part at /test/test.json, which finds the resource discovery file no problem. It even lists /test/testing. But once you click on it, nothing seems to happen. If I move it back up to the root, it works without issue.

    {
      'apiVersion' => '0.2',
      'swaggerVersion' => '1.0',
      'basePath' => 'http://33.33.33.10:9292',
      'apis' => [
        {
          'path' => '/test/test.{format}',
          'description' => 'something about testing'
        }
      ]
    }

would like to have XML response option in UI

dist is generated from the build, it should not be under source control

Swagger seems to assume that resources have a URL with a {format} path parameter which can be “json” or “xml”, like “/pet.json/1” or “/pet.xml/1”. I'm still pretty new to REST API design, but from what I understand from reading the O'Reilly “REST API Design Rulebook" including such a format parameter in the URL isn't considered good REST design as it assigns two different URLs to what is really the same resource (but in two different representations). The relevant rule in the book is “Rule: File extensions should not be included in URIs” which appears on page 13. The author recommends that “REST API clients should be encouraged to utilize HTTP’s provided format selection mechanism, the Accept request header ... when multiple representations are available.”

The index.html file in src/main/html/ expects the lib/ directory to exist in src/main/html/ it is also looking there for swagger-ui.js, which I cannot find anywhere.

spec.html in src/test/ expects all the jasmine files to live in lib/ when, in fact, they live in bin/.

Using
nodejs - v0.8.11
coffee-script - latest
cake - latest

C:\Arjun\projects\swagger-ui>cake dist
path.existsSync is now called fs.existsSync.
Build distribution in ./dist
: Reading src/main/coffeescript/SwaggerUi.coffee
: Reading src/main/coffeescript/view/HeaderView.coffee
: Reading src/main/coffeescript/view/MainView.coffee
: Reading src/main/coffeescript/view/ResourceView.coffee
: Reading src/main/coffeescript/view/OperationView.coffee
: Reading src/main/coffeescript/view/ParameterView.coffee
: Precompiling templates...
: Compiling src/main/template/main.handlebars
: Compiling src/main/template/operation.handlebars
: Compiling src/main/template/param.handlebars
: Compiling src/main/template/param_list.handlebars
: Compiling src/main/template/param_readonly.handlebars
: Compiling src/main/template/param_readonly_required.handlebars
: Compiling src/main/template/param_required.handlebars
: Compiling src/main/template/resource.handlebars

C:\Arjun\servicemesh\projects\swagger-ui\Cakefile:59
throw err;
^
Error: Command failed: 'node_modules' is not recognized as an internal or external command,
operable program or batch file.

at ChildProcess.exithandler (child_process.js:540:15)
at ChildProcess.EventEmitter.emit (events.js:96:17)
at maybeClose (child_process.js:638:16)
at Socket.ChildProcess.spawn.stdin (child_process.js:815:11)
at Socket.EventEmitter.emit (events.js:93:17)
at Socket._destroy.destroyed (net.js:357:10)
at process.startup.processNextTick.process._tickCallback (node.js:244:9)

The README says:

If you enter an api key in swagger-ui, it sends a parameter named 'api_key' as a query (or as a header param if you've enabled it as described above).

But although I set "supportHeaderParams" to true, it seems "api_key" is still passed as a query parameter.

I pulled down the current version of swagger-ui to work with the newest version of swagger-core, and it appears to be broken since the "new build" commit (4ce5b8f). Once I hit that commit, I'm eternally stuck with a "Fetching API List...", whether exploring the live petstore, a locally-running petstore, or my own work.

In the console, I see "GET http://petstore.swagger.wordnik.com/resources 404 (Not Found)".

Failing in Safari and Chrome.

I know you are trying to support some alternative formats, but shouldn't this be backward compatible?

For example in the pet store, a pet object can be posted in "post /pet.json". The Pet object is already defined as a model with property descriptions and this information is available in the resource JSON files.

It would be very nice to add a "View model/object description" link at the bottom of de implementation notes and above the parameters. If a user clicks the link, then he will see exactly how the pet object he wants to post must look like!

It's that simple: in the new version the parameters of type 'query' don't work. Except only the ones that relate to 'auth' or 'api'?

I am returning a 'Range' header on the response. I see it in the response headers when inspecting the HTTP response, in addition to other auto generated headers, but it does not show in the Headers block in the UI. Not a huge deal, but since this is useful as documentation to a consumer, it would be nice to show it explicitly.

if one defines a parameter to be of the 'header' type, then this parameter is still appended to the URL as though it was a 'query' parameter

I have an API with tree resources, which are handled by a single handler method in the implementation. The URL template for these resources is something like: (in RFC 6570 syntax)

/tree.{format}/{name}{/nodeid*}

So /tree.json/foo points to a JSON representation of the root node of the tree named “foo”, /tree.json/foo/4/2 points to the second child node of the fourth child node of the root node and so on. There doesn't seem to be a convenient way to describe these resources as a single API GET operation in Swagger. The Swagger specification implies that the “allowMultiple” attribute can only be used for query parameters, not for path parameters.

there schould be a replace of meta-characters in all swagger-ui functions

If you wish to use any of the meta-characters ( such as !"#$%&'()*+,./:;<=>?@[]^`{|}~ ) as a literal part of a name, you must escape the character with two backslashes: .

ex:

toggleEndpointListForResource: function(resource) {
    var elem = $('li#resource_' + resource.replace(/[!"#$%&'()*+,.\/:;<=>?@\[\\\]\^`{|}~]/g,"\\$&") + ' ul.endpoints');
    if (elem.is(':visible')) {
        Docs.collapseEndpointListForResource(resource);
    } else {
        Docs.expandEndpointListForResource(resource);
    }
},

Our server doesn't have a concept like api key. Instead, since it uses sessions, it has a special kind of session. For example, while testing, developers can append "?sessionID=sessionDebug" to the URL for testing purposes, to avoid asking for a proper session (and that would imply logging in, etc.).
The existing api key feature does exactly this, except that it always creates a parameter name 'api_key'. It would be nice if we could explicity set what this parameter would be named.
Like the recently created "supportedSubmitMethods" parameter, there could be a new one called "apiKeyName" that could control the name of the URL parameter of the api key (it would default to "api_key")

When specifying sibling top-level resources (/resource1, /resource2), swagger-ui collapses all subsequent top-level resources into the UI container for the first:

• Screenshot -- http://cl.ly/Fk2F
• Gist -- https://gist.github.com/309055b2c1401918e2f1

The #! urls for both /user and /team in the screenshot are as follows:

• /user
  • Swagger UI #! href: http://localhost:3000/docs/#!//postUser_POST
  • Operations file (gist)
• /team
  • Swagger UI #! href: http://localhost:3000/docs/#!//postTeam_POST
  • Operations file (gist)

I tried playing around with the path on the apis for each resource and they would collapse as long as there was an operation that was the same path as the top-level resource. If I changed the path in the operations file for the create (POST) for either user or team to even just append a slash (/) then the collapsing behavior disappeared.

EDIT: It isn't just any change that makes the problem go away. There has to be a slash to trigger it.