dapperdox / dapperdox

Beautiful, integrated, OpenAPI documentation.

DapperDox   

Beautiful, integrated, OpenAPI documentation.

Themed documentation generator, server and API explorer for OpenAPI (Swagger) Specifications. Helps you build integrated, browsable reference documentation and guides. For example, the Companies House Developer Hub built with the alpha version.

Features

• Author full documentation in GitHub Flavoured Markdown.
• Document multiple API specifications as a suite of cross-referenced products.
• Seamlessly overlay content onto the automatically generated reference documentation.
• Integrate the built-in API explorer with your APIs and authentication model.
• Proxy your developer platform, allowing full integration of API key management.
• Choose from multiple themes, or create your own.

Documentation and usage

Detailed usage instructions are available on the DapperDox website http://dapperdox.io.

Quickstart

We provide the lastest release builds for the most common operating systems and architectures, which you can download from releases, or you can build from source by cloning this repo.. See downloads for further information.

Build from source

First build DapperDox (this assumes that you have your golang environment configured correctly):

go get && go build

Running DapperDox

Start up DapperDox, pointing it to your OpenAPI 2.0 specification file:

./dapperdox -spec-dir=<location of OpenAPI 2.0 spec>

DapperDox looks for the file swagger.json at the -spec-dir location, and builds reference documentation for the OpenAPI specification it finds. For example, the obligatory petstore OpenAPI specification is provided in the examples/specifications/petstore directory, so passing parameter -spec-dir=examples/specifications/petstore will build the petstore documentation.

DapperDox will default to serving documentation from port 3123 on all interfaces, so you can point your web browser at http://127.0.0.1:3123 or http://localhost:3123.

For an out-of-the-box example, execute the example run script:

./run_example.sh

This demonstrates many of the configuration options available. See configuration.

Acknowledgements

Many thanks to Ian Kent who spiked the Golang implementation of DapperDox as part of a bigger project. His commit history was lost when DapperDox was extracted into a stand-alone project, but its core retains his valuable work.

David Mort for painstaking testing, and bug fixing.

dapperdox's Issues

Random sorting of operations on summary pages

Operations listed at "summary" pages obviously don't respect ordering in JSON source. Each time I re-run dopperdox I see different order of operations. This is pretty inconvenient.

Theme and theme dir ignored from environment variable

Equivalent to -theme and -theme-dir commandline options should be THEME and 'THEME_DIR` environment variables. But I've found that Dapperdox ignores them (I run on 1.1.1-linux-amd64). Currently the only way to set these parameters are via commandline.

Sidenote: There's a typo in http://dapperdox.io/docs/configuration-guide - docs says -themes-dir and THEMES_DIR but actual option and environment name is in singular form (-theme-dir and THEME_DIR). I'm going to fix it myself.

api key name and location is ignored

The api key name and in options are ignored. Instead the api key is always added to the request using the query argument key

When having

 "securityDefinitions": {
    "some_key": {
      "type": "apiKey",
      "name": "myApiKey",
      "in": "header"
    }
  }

and

the key is not added as a header but as a query argument named key:

After changing the security definition to use a query like so:

 "securityDefinitions": {
    "some_key": {
      "type": "apiKey",
      "name": "myApiKey",
      "in": "query"
    }
  }

the query argument key is still used and not myApiKey.

Minimal example to reproduce:

{
  "x-navigateMethodsByName": true,
  "info": {
    "title": "minimal"
  },
  "swagger": "2.0",
  "host": "localhost:3123",
  "paths": {
    "/account": {
      "get": {
        "summary": "list",
        "security": [ { "some_key": [] } ],
        "responses": {
          "200": {
            "description": "Success",
              "schema": {
                  "title": "response",
                  "type": "string"
            }
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "some_key": {
      "type": "apiKey",
      "name": "myApiKey",
      "in": "query"
    }
  }
}

What syntax is [: :]?

I have just started using dapperdox and have never written Go.
Furthermore, I have never seen the syntax [: :] before. It would be great to have an overview of the kind of properties / control structures (if...else, for-loops, etc) that is available so that I can best make use of them when creating my own template.

Loading specifications fails on Windows

User has reported that they cannot load a JSON specification file; not even the petstore example that DapperDox provides.

The following steps outline the process that I followed.

Used Swashbuckle (with some configurations) to build a valid Swagger JSON file.
Installed Go and configured the necessary PATH variables.
Used Go to obtain dependencies and build DapperDox from source code.
Pointed DapperDox to my swagger.json file.

./dapperdox -spec-dir=C:\APIcodedir\output -spec-filename=swagger.json

The command returns the following error:

[XVlBzgbaiCMRAjWwhTHc] [info] GET /swagger.json (404, 0s)

Load specification error: could not access document at "http://localhost:3123/swagger" [404 Not Found]

I have tried specifying the -spec-dir only (without -spec-filename), in addition to using -spec-filename (without -spec-dir). All options result in the same 404 error. I tried specifying the petstore example that the DapperDox source includes, but same the error returns.

One of our developers tried this approach on his machine, which achieved the same results. Am I missing something? Any help is greatly appreciated!

Changes to go-openapi expand spec cause DapperDox build failure

go-openapi adds ExpandOptions to spec.Load. Additional parameter will be required to get build working.

It's unclear if tags are mandatory (they seem to be)

I've just tried using swaggerly with an existing swagger.json which didn't have any tags. The README was ambiguous to me about whether tags were required, but the result was that without tags, I wasn't getting any content.

It'd be good if the README was clearer that the use of tags is required, and if the tool spat out a warning message if no tagged paths are found.

Styling of rendered GFM content does not match theme

GFM files are rendered using standard Github HTML/CSS. The renderer need extending so that themes can provide the appropriate markup.

Definitions in API reference

Hi, I've been looking at documentation tools and I really like the work you've done on swaggerly. The ability to augment an OpenAPI spec with markdown documents is great.

I was wondering what your plans are for documenting model definitions?

As an example, the current spec describes a model for Pet that is extended by Cat and Dog subtypes:

{
  "definitions": {
    "Pet": {
      "type": "object",
      "discriminator": "petType",
      "properties": {
        "name": {
          "type": "string"
        },
        "petType": {
          "type": "string"
        }
      },
      "required": [
        "name",
        "petType"
      ]
    },
    "Cat": {
      "description": "A representation of a cat",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "huntingSkill": {
              "type": "string",
              "description": "The measured skill for hunting",
              "default": "lazy",
              "enum": [
                "clueless",
                "lazy",
                "adventurous",
                "aggressive"
              ]
            }
          },
          "required": [
            "huntingSkill"
          ]
        }
      ]
    },
    "Dog": {
      "description": "A representation of a dog",
      "allOf": [
        {
          "$ref": "#/definitions/Pet"
        },
        {
          "type": "object",
          "properties": {
            "packSize": {
              "type": "integer",
              "format": "int32",
              "description": "the size of the pack the dog is from",
              "default": 0,
              "minimum": 0
            }
          },
          "required": [
            "packSize"
          ]
        }
      ]
    }
  }
}

It would be great to see an example of how this could be rendered in swaggerly.

The APIs I tend to work with are quite simple in terms of operations, but have a complex data model, and models are reused by different resources. Ideally I'd like to be able to indicate whether models should be inlined with the method reference or go in a different section.

I noticed there is some support for resource descriptions in the uber example, (http://localhost:3123/resources/profile-resource?v=latest) - does this extend to collections and nested data structures? Is there a way to include it in the navigation tree?

Author cannot control the navigation order of 'guides'.

Navigation meta data allows guide pages to be added to the site navigation, but the ordering is always alphanumeric. Authors require the means to control this ordering.

Support for Schema Validation

Since we are defining the Response Definition (Schema), Validation of response from server against the definition would be a great feature. For now the same can be achieved in Swagger through Middleware option available in 'swagger-tools'. But it would be a great to have validateResponse flag as configuration without any coding tasks involved.

https://github.com/apigee-127/swagger-tools

Sample code:
var swagger = require('swagger-tools');
var swaggerObject = require('./samples/2.0/petstore.json'); // This assumes you're in the root of the swagger-tools

var connect = require('connect');
var http = require('http');
var app = connect();

// Initialize the Swagger Middleware
swagger.initializeMiddleware(swaggerObject, function (middleware) {
// Interpret Swagger resources and attach metadata to request - must be first in swagger-tools middleware chain
app.use(middleware.swaggerMetadata());

// Provide the security handlers
app.use(middleware.swaggerSecurity({
oauth2: function (req, def, scopes, callback) {
// Do real stuff here
}
}));

// Validate Swagger requests
app.use(middleware.swaggerValidator({

validateResponse: true

}));

// Route validated requests to appropriate controller
app.use(middleware.swaggerRouter({useStubs: true, controllers: './controllers'}));

// Serve the Swagger documents and Swagger UI
// http://localhost:3000/docs => Swagger UI
// http://localhost:3000/api-docs => Swagger document
app.use(middleware.swaggerUi());

// Start the server
http.createServer(app).listen(3000);
});

Allow multiple config values to be passed by environment variables

For example, -document-rewrite-url can be specified multiple times on the command line, but the equivalent DOCUMENT_REWRITE_URL environment variable can only be given once. This applies to many of the configuration environment variables.

Two options exist:

1. to allow multiple values to be passed in a single environment variable, using some delimiter.
2. to allow multiple environment variables to be supplied.

Option 1 is complicated by the choice of delimiter, and there is no clear best fit.
Option 2 could number the environment variables:
DOCUMENT_REWRITE_URL=
DOCUMENT_REWRITE_URL_0=
DOCUMENT_REWRITE_URL_1=
DOCUMENT_REWRITE_URL_2=

OpenAPI 3.0

Would you support that in the near future?
https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md

Thx.

Cannot define a request body in documentation.

When defining a request body using swaggerly:

{ "name": "template-name", "description": "Template name to be rendered", "required": true, "in": "body", "schema": { "type": "hash", "items": { "$ref": "#/definitions/links" } } },

I get the error message:

template: layout:55:13: executing "layout" at : error calling yield: template: fragments/explorer:24:24: executing "fragments/explorer" at <.Method.BodyParam>: range can't iterate over <spec.Parameter Value>

appearing in the browser

API Explorer does not report unsuccessful status codes

For example, 404 is folded into a "Failure contacting API" response.

object properties in resource view show description of object and not description of the property

In the list of properties of a resource, the description of an object is taken from the referenced object and not from the property. This gets confusing if the same object is used multiple times as different properties.
I would expect to see the description of the property and not the description of the object:

I tried to change it myself but my knowledge about Go is very poor.

The spec file I used:

{
  "x-navigateMethodsByName": true,
  "definitions": {
    "AccountList": {
      "type": "object",
      "title": "AccountList",
      "properties": {
        "first": {
          "type": "object",
          "description": "first property",
          "$ref": "#/definitions/MyObject"
        },
        "second": {
          "type": "object",
          "description": "second property",
          "$ref": "#/definitions/MyObject"
        }

      }
    },
    "MyObject": {
      "type": "object",
      "title": "My Object",
      "properties": {
        "second": {
          "description": "second",
          "type": "string"
        }
      }
    }
  },
  "info": {
    "title": "minimal"
  },
  "swagger": "2.0",
  "paths": {
    "/account": {
      "get": {
        "summary": "List accounts",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/AccountList"
            }
          }
        }
      }
    }
  }
}

additionalProperties currently not supported

This is required to handle map responses.

creating an api-group overlay breaks everything

If I create an API group overlay in the example and run it, I get request timeouts and nothing in the browser when opening http://localhost:3123/swagger-petstore/reference/everything-about-your-pets/get-pet-by-id

If I remove the API group overlay file everything works as expected.

To reproduce:

Create a file examples/overlay/assets/sections/swagger-petstore/templates/reference/everything-about-your-pets.md containing:

Overlay: true

[[description]]
Hello

Update run_example.sh to include -assets-dir=./examples/overlay/assets and run it:

$ ./run_example.sh 
2017/02/09 15:38:09 DapperDox server version 1.1.0 starting
2017/02/09 15:38:09 Configuration:
2017/02/09 15:38:09 	          BindAddr: 0.0.0.0:3123
2017/02/09 15:38:09 	         AssetsDir: ./examples/overlay/assets
2017/02/09 15:38:09 	  DefaultAssetsDir: assets
2017/02/09 15:38:09 	           SpecDir: examples/specifications/petstore/
2017/02/09 15:38:09 	      SpecFilename: [/swagger.json]
2017/02/09 15:38:09 	             Theme: default
2017/02/09 15:38:09 	          ThemeDir: 
2017/02/09 15:38:09 	          LogLevel: info
2017/02/09 15:38:09 	           SiteURL: http://localhost:3123
2017/02/09 15:38:09 	    SpecRewriteURL: [petstore.swagger.io=PETSTORE.swagger.io]
2017/02/09 15:38:09 	DocumentRewriteURL: []
2017/02/09 15:38:09 	     ForceSpecList: %!s(bool=false)
2017/02/09 15:38:09 	        ShowAssets: %!s(bool=true)
2017/02/09 15:38:09 	         ProxyPath: []
2017/02/09 15:38:09 	    TLSCertificate: 
2017/02/09 15:38:09 	            TLSKey: 
2017/02/09 15:38:09 listening on 0.0.0.0:3123
2017/02/09 15:38:09 Registering specifications
2017/02/09 15:38:09 [XVlBzgbaiCMRAjWwhTHc] [info] GET /swagger.json (200, 233.893µs)
2017/02/09 15:38:09 Registering reference documentation
2017/02/09 15:38:09 Registering guides
2017/02/09 15:38:09 listening on 0.0.0.0:3123 for unsecured connections
2017/02/09 15:38:17 [tcuAxhxKQFDaFpLSjFbc] [warn] request timed out
2017/02/09 15:38:46 [XoEFfRsWxPLDnJObCsNV] [warn] request timed out
2017/02/09 15:38:54 [lgTeMaPEZQleQYhYzRyW] [warn] request timed out

API spec endpoints with same summary break the UI

Having multiple endpoints with the same summary causes one to be overwritten by the other (e.g., for our API, both /a/1/b/2 and /b/2/a/1 are effectively the same resource)

More info at ONSdigital/dp-apipoc-server#1

Local address being used for spec download instead of relative to site.

`-document-rewrite-url` doesn't work as expected

From the documentation, it looks as though I should be able to do:
-document-rewrite-url=from.url=to.url
but this doesn't appear to have any effect on the host parameter in my swagger.json file, meaning the API explorer and endpoint URLs always show the original host

We can replace the host in the json file, but (with Docker) means building a new container for each environment, rather than customising it with environment variables

Object property examples not displayed

Definitions with "inline" property example values, i.e. with example along with property, are not displayed in at resource page.

Definition like this

  UserMeResponse:
    type: object
    title: User object
    properties:
      id:
        type: integer
        minimum: 0
        description: User ID.
        example: 2929                 # << property example
      first_name:
        type: string
        description: User's first or given name.
        example: John
      last_name:
        type: string
        description: User's last or family name.
        example: Appleseed
      email:
        type: string
        format: email
        description: User's email.
        example: [email protected]
      phone:
        type: string
        description: User's phone.
        example: [phone]
    required:
      - id
      - email

have no example at resource page. But modified to:

  UserMeResponse:
    type: object
    title: User object
    properties:
      id:
        type: integer
        minimum: 0
        description: User ID.
      first_name:
        type: string
        description: User's first or given name.
      last_name:
        type: string
        description: User's last or family name.
      email:
        type: string
        format: email
        description: User's email.
      phone:
        type: string
        description: User's phone.
    required:
      - id
      - email
    example:                # << object example
      id: 2929
      first_name: "John"
      last_name: "Appleseed"
      email: "[email protected]"
      phone: "[phone]"

has example section

IMHO property examples shouldn't be silently loss like now. Other tools, like editor.swagger.io, displays them.

Question is what examples take precedence. Editor.swagger.io overrides property example if there is the object example.

README is unclear if the second markdown file being in the 'level2' folder is significant

The README is unclear if the second markdown file being in the 'level2' folder is significant. There's sort of an implication that it is, but it doesn't seem to affect the display.

Support for JSON editor

Enabling Editor for feeding individual JSON parameters for 'Body' in POST method, instead of feeding the complete JSON.

https://github.com/jensoleg/swagger-ui

A JSON editor for the request body (disabled by default).

Swagger JSON editor example

            jsonEditor: true,
            jsonEditorOptions: {
                disableProperties:false,
                disableEditJson:false,
                removeEmptyProperties:true,
                noDefaultProperties:true
            },
            docExpansion: "none",
            sorter: "alpha",

Allow relative file paths

Not a bug or issue, but might be a valid enhancement to allow this, now that go-openapi supports relative local file $ref's

If this means of specification access (over the built-in http://...) were used, then DapperDox would not be able to rewrite any specification URL's. But it might be useful.

URL wrapping should be improved.

Long URLs do not wrap correctly.
Method URL's should wrap, or at least scroll horizontally (with a visible scroll bar).

Resource not found if resource is only present in a request body

If a resource definition is only used by a request body, then it does not get added to the resource list for a method. Only response definitions are stored in this list.

What needs to happen is that a (filtered) request body definition is not stored if an (unfiltered) response definition is stored, otherwise it is. And a response definition always overwrites a request body resource (as it is the unfiltered super-set resource).

Customisation of reference documentation using GFM

Work in progress.
The standard set of default pages need to be customisable. This is used extensively in the http://developer.companieshouse.gov.uk which uses the alpha implementation of Swaggerly.

The implementation will allow GFM pages to be created with custom anchors which reference identified locations in the theme page templates for API, method and resource, and Swaggerly will merge the GFM content into the generated reference page.

Allow content to be added to the default templates for:

1. An API (endpoint / path) summary page
2. An API method page
3. A resource page

additionally:

1. All method pages for a particular API endpoint

and

1. A specific API endpoint summary
2. A specific API endpoint method
3. A specific resource

It would be nice if parameters under "explore this API" are prefilled with the defaults

If the parameters are already prefilled with the default value from the spec. it would make it easier for the reader of the documentation to test the API and see what it does.

Minimal example:

{
  "x-navigateMethodsByName": true,
  "info": {
    "title": "minimal"
  },
  "swagger": "2.0",
  "host": "localhost:3123",
  "paths": {
    "/account": {
      "get": {
        "parameters": [ {
          "name": "something",
          "in": "query",
          "description": "A parameter",
          "type": "string",
          "default": "a default"
        } ],
        "summary": "list",
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "title": "response",
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Date format not being displayed

Currently the raw type of string is being displayed, not the associated format of date or date_time.

Dockerfile and pre-built images on DockerHub would be useful

We're looking at building a Docker container to host our documentation - at the moment this is a complicated build process which involves cloning DapperDox and building from source.

It'd would be cleaner if we could use FROM dapperdox and extend a pre-built image

Title of property is shown as extra object

When rendering the following schema:

"properties": {
          "with-title": {
              "type": "string",
              "title": "title"
          },
          "with-title-and-description": {
              "type": "string",
              "title": "title",
              "description": "description"
          },
          "without-title": {
              "type": "string",
              "description": "description"              
          }
      }

The titels of the properties are shown as additional object keys as shown below:

I would have expected the first column to just read:

• with-title
• with-title-and-description
• without-title

Is this an intended feature?

Full spec to repoduce:

{
    "x-navigateMethodsByName": true,
    "definitions": {
    "AccountList": {
      "type": "object",
      "title": "AccountList",
      "properties": {
          "with-title": {
              "type": "string",
              "title": "title"
          },
          "with-title-and-description": {
              "type": "string",
              "title": "title",
              "description": "description"
          },
          "without-title": {
              "type": "string",
              "description": "description"              
          }
      }
    }
  },
  "info": {
    "title": "minimal"
  },
  "swagger": "2.0",
  "paths": {
    "/account": {
      "get": {
        "summary": "List accounts",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "schema": {
              "$ref": "#/definitions/AccountList"
            }
          }
        }
      }
    }
  }
}

Mimetypes set by consumes/produces are ignored

The global and per request consumes and produces properties are ignored.

Dapperdox does not provide a way to select the mime type of data being send but always assumes data send is "application/json".
It also does not provide a way to select the mime type of the data you want to receive. It seems to not touch the Accept header which in my case means it is set to "text/plain, */*; q=0.01" causing the server to return XML instead of JSON.

I would expect dropdowns listing the mimetypes listed in the consumes/produces to select what data is send/expected.

In swaggerui a dropdown is shown for selecting what the mime type is of the body send or the mime type of the expected result:

Minimal example:

{
  "x-navigateMethodsByName": true,
  "info": {
    "title": "minimal"
  },
  "swagger": "2.0",
  "host": "localhost:3123",
  "paths": {
    "/account": {
      "post": {
        "parameters": [ { "in": "body", "schema": { "type": "string", "title": "something" } } ],
        "summary": "post",
        "consumes": [
          "application/json",
          "application/json-patch+json"
        ],
        "produces": [
          "application/json",
          "text/xml"
        ],
        "responses": {
          "200": {
            "description": "Success",
              "schema": {
                  "title": "response",
                  "type": "string"
            }
          }
        }
      }
    }
  }
}

Many csrf tokens generated for a page

Not necessarily a problem, but would like to check what is usual.

Reloading specifications

Hi,

I am doing some evaluation with Win amd64 precompiled release.
I added some swagger.json for a new specification and it works OK.
I would like to be able to make changes in swagger.json, hit Refresh in browser and see them.
Is that even an option for now, or I need to stop/start every time when I have a change in spec files?

Regards,
Bojan

Array types in schemas displaying inconsistently

This is a follow up to #7 which was a broader question about resource pages. Since then I've created a few branches to experiment with different schemas.

One of the things I looked at was the handling of array types within the example spec, as I suspected I was using these wrong.

https://github.com/MatMoore/swaggerly/commit/7764d69c8efbeed40f923b80cf3a443c8cc70ae0
In this commit, I took the Activities resource from the existing example.

This currently renders an item named history.activity-resource with type array. I wondered if this is supposed to render as something like history / array[activity] instead.

I also added a "children" object to this resource with the same type (Activites) just to see what would swaggerly would do with it. This one rendered as children / array.

With other schemas I've seen this render differently, e.g. having type array[array] - see issue #13.

Ideally I'd prefer to render a property list table without the nested fields. I think there will be cases where inlining the child object fields adds too much noise, particularly if there are a lot of them. An alternative would be to display the type as something like array[activity] and just allow the user to click through to the type parameter.

Definition/resource member filtering for readOnly incorrectly applied GET responses

It appears that only one copy of a resource is maintained, which could be the readOnly filtered resource. This seems to have broken recently.

Aborts if no "schema" member present with an in: body parameter

Needs error checking for this case.

Provide an option to optionally ignore specifications which failed to load

Right now dapperdox fails if any of the specified specifications failed to load for any reason:

for _, specFilename := range cfg.SpecFilename {
	...
	err = specification.Load(specFilename, specHost)
	if err != nil {
		return err
	}
	...
}

Currently we are playing with a fork which loads specifications from multiple remote locations.

It would be really handy to have an option to skip specs which failed to load because of connectivity issues/syntax errors/timeouts/etc. That would also allow to avoid modifying a configuration every time one of the locations is failing.

Response headers not displayed in GUI

"responses": {
                    "201": {
                        "description": "The URL to the PDF is returned in the Location header",
                        "headers": {
                            "Location": {
                                "description": "The location the assets can be retrieved from",
                                "type": "string"
                            }
                        }
                    },
                    "400": {
                        "description": "Unable to handle given request"
                    }
                }

Running swaggerly against this code does not show the Location Response header in the GUI:

Allow the processing of multiple OpenAPI specifications

Only a single OpenAPI specification can be processed currently. The intention is to allow multiple specifications to be built into a consolidated set of documentation. For example, the specification for authentication and the specification for the API that requires authentication.

Edit: The above turns out to be a little involved, as there needs to be a parent for each distinct spec (authentication, foo, bar etc), and currently there is no parent, and api, info, guides, resources are all at the top level. URLs will also change, containing that the specification 'identifier':

/reference/API_ID/estimates-of-price/get

In addition, a single specification could be split into multiple specification files, which is useful if you're following the 12 factor app approach, and have your API split into multiple, independently releasable, deployable and version-able repos. In this case it could be desirable to have your API specifications split up, so the Swaggerly grouping/merging of API specs would need to be governed by info.title.

I would see the 'homepage' listing all the API's which are available (authentication, foo, bar etc) and allow users to navigate between them (and documentation writers to link between them).

Live Reload on changes made

I would like to ask whether there is any live reload or auto reload functionality when a changes has been made to files watching?

Is it possible to support oneOf ?

Currently it seems using oneOf in the properties is not supported:

"properties": {
  "value": {
    "description": "A string or object",
    "oneOf": [ 
      {  
        "type": "string" 
      },
      {
        "type": "object",
        "properties": {
          "subvalue": {
            "description": "The string",
            "type": "string"
          }
        }
      }
    ]
  }
}

is rendered as:

I can imagine it will be difficult to render cleanly but I was wondering if it will be supported someday.
Thanks.

Support -spec-url

DapperDox supports -spec-dir and -spec-filename arguments. To be able load schemas dynamically additional -spec-url needs to be supported:

To make it work dapper dox is started with the following parameters:

./dapperdox -bind-addr=0.0.0.0:8080 -spec-dir=/spec \
-spec-filename=service1.json \
-spec-filename=service2.json

We need to support remote urls, something like:

./dapperdox -bind-addr=0.0.0.0:8080 \
-spec-url=http://service1/swagger.json \
-spec-url=http://service2/swagger.json

Array type in resource model rendering incorrectly as object

The following is a fragment from a response definition in my swagger doc:

"definitions": {
        "Dataset": {
            "title": “Dataset model”,
            "type": "object",
            "properties": {
                "items_per_page": {
                    "type": "integer",
                    "description": "Number of items returned in a page of response"
                },
                "start_index": {
                    "type": "integer",
                    "description": "Index of the starting item"
                },
                "total_items": {
                    "type": "integer",
                    "description": "The total number of items in dataset"
                },
                "items": {
                    "description": “Dataset items",
                    "minItems": 0,
                    "uniqueItems": true,
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/Metadata"
                    }
                }
            }
        },
        "Metadata": {
            "title": “Metadata model",
            "type": "object",
        .
        .
        .

DapperDox renders the “Dataset.items” resource incorrectly as an object rather than an array:

{
    "items": {
        "id": "string",
        "kind": "string",
        "links": [
            {
                "url": "string"
            }
        ],
        "title": "string"
    },
    "items_per_page": "integer",
    "start_index": "integer",
    "total_items": "integer"
}

Swagger UI correctly renders it as:

{
  "items_per_page": 0,
  "start_index": 0,
  "total_items": 0,
  "items": [
    {
      "id": "string",
      "kind": "string",
      "title": "string",
      "links": [
        {
          "url": "string"
        }
      ]
    }
  ]
}

The items field is an array, not an object.

Polymorphism in models

This is a follow up to #7 which was a broader question about resource pages. Since then I've created a few branches to experiment with different schemas.

The open api spec talks about polymorphic model definitions here: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#composition-and-inheritance-polymorphism

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, Swagger adds the support of the discriminator field. When used, the discriminator will be the name of the property used to decide which schema definition is used to validate the structure of the model. As such, the discriminator field MUST be a required field. The value of the chosen property has to be the friendly name given to the model under the definitions property. As such, inline schema definitions, which do not have a given id, cannot be used in polymorphism.

I noticed we were already using allOf in the examples:
Pet is a supertype of Cat and Dog, and has a petType discriminator. Pet wasn't referred to directly in any responses though.

What I'd like to do is declare that a response contains pets, and somehow be able to see what the Cat/Dog fields are from the Pet resource page.

I added an example of what I mean in this commit: https://github.com/MatMoore/swaggerly/commit/b000bb42d64ff79c6bea11db3aecc975ae10fd90

My questions are:

• Do I understand the spec correctly when it comes to polymorphic responses?
• Is it something you'd want to support in swaggerly?

Can't load Javascripts in localhost

Hi all,
I'm testing and configuring a documentation with dapperdox. In static directory I have:

css/style.css -> Load OK
images/myfavicon.png -> Load OK
javascripts/jquery.min.js - explorer.js etc... -> NOT Load
[info] GET /javascript/explorer.js (404, 1.0022ms) - With debug same error in browser

All others javascripts into directories exemple doesn't work.
Why I find my images but javascript no?
Thanks all for support
Vito

Defining schemas within a response object

This is a follow up to #7 which was a broader question about resource pages. Since then I've created a few branches to experiment with different schemas.

https://github.com/MatMoore/swaggerly/commit/02212d55a499700e3e342a8cfaf24bb55d59e3ac is a simplified version of my spec.

I've been using https://github.com/swagger-api/swagger-node to validate.

With this example, my Response page describes the document field as array[array]. I compared this to the examples discussed in #11, and the only obvious difference is that in this schema I describe my schema inline in a response, e.g.

      "responses": {
 +          "200": {
 +            "description": "Results of the search",
 +            "schema": {
 +              "title": "Search response",
 +              "properties": {

rather than using a ref to a model defined elsewhere. Is there any reason why this wouldn't be valid?

A related problem I noticed is trying to add a non-object response. For example, the swagger pet store example has a login request that returns a plain string. Swagger-ui presents this as "Response Class (Status 200) string": http://petstore.swagger.io/#!/user/loginUser

Unfortunately I don't seem to be able to do the same thing in swaggerly. I committed an example here https://github.com/MatMoore/swaggerly/commits/simple-response-example - this basically expands the string field into its own resource, which would be quite confusing for a non-json content type.

Add a license

Please add a license, as is it appears that technically, no one is allowed to use this repository

https://choosealicense.com/no-license/

What does [: yield :] yield?

I am currently modifying the root page of this and I noticed there is [: yield :] in the body.tmpl.
I can't seem to trace what does this do. Please advice