sourcey / spectacle Goto Github PK

View Code? Open in Web Editor NEW

1.3K 18.0 338.0 2.26 MB

Beautiful static documentation generator for OpenAPI/Swagger 2.0

Home Page: https://sourcey.com/spectacle

License: Other

JavaScript 21.09% CSS 20.99% HTML 37.09% Makefile 0.06% Dockerfile 0.05% SCSS 11.15% Handlebars 9.57%

spectacle's Introduction

Spectacle

The gentleman at REST

Spectacle generates beautiful static HTML5 documentation from OpenAPI/Swagger 2.0 API specifications.

The goal of Spectacle is help you "save time and look good" by providing an extensible platform for auto generating your REST API docs. The default layout is a three column single page, similar to those employed by Stripe and Intercom.

See a demo of Spectacle in action here: http://cheesestore.github.io

Features

OpenAPI/Swagger 2.0 support: Support for the latest OpenAPI/Swagger specification.
Highly configurable: Easily configurable Handlebars templates and SCSS styles so you can add your own design and flavour without going bald. See Custom Builds
Markdown support: Render markdown written in any of your API descriptions.
Remote file references: Support for swagger specs split across multiple files.
Clean responsive design: Responsive HTML5 and CSS3 layout built with Foundation 6 that looks great on all devices and screen sizes.
Embed into your existing website: An embedded option so that generate partial docs without a HTML <body> for convenient integration into your existing website.
Live preview developer mode: Development mode that starts a local HTTP server with a file watcher and live reload so you can preview live changes in your browser as you update your spec.

Usage

Simply install Spectacle from npm like so:

npm install -g spectacle-docs

Next pass your swagger.json document use the CLI to generate your documentation.

spectacle -d your_swagger_api.json

# Or use the cheese.json example to test it out
# spectacle -d -l test/fixtures/cheese.png test/fixtures/cheese.yml

Your generated documentation will be located in the public directory by default. You can either copy the generated HTML to your web server, or view your docs by pointing your browser to http://localhost:4400/.

Docker

Docker images are included that allow Spectacle to be run from the inside. It's useful, for instance, in a Gitlab CI pipeline. Thanks @alexeiaguiar.

How to use it: docker run -it sourcey/spectacle /bin/sh

Configuration Options

The basic CLI options are detailed below:

$ spectacle -h

  Usage: spectacle [options] <specfile>

  Options:

    -h, --help                   output usage information
    -V, --version                output the version number
    -C, --disable-css            omit CSS generation (default: false)
    -J, --disable-js             omit JavaScript generation (default: false)
    -e, --embeddable             omit the HTML <body/> and generate the documentation content only (default: false)
    -d, --development-mode       start HTTP server with the file watcher (default: false)
    -D, --development-mode-live  start HTTP server with the file watcher and live reload (default: false)
    -s, --start-server           start the HTTP server without any development features
    -p, --port <port>            the port number for the HTTP server to listen on (default: 4400)
    -P, --port-live <port>       the port number for the live reload to listen on (default: 4401)
    -t, --target-dir <dir>       the target build directory (default: public)
    -f, --target-file <file>     the target build HTML file (default: index.html)
    -a, --app-dir <dir>          the application source directory (default: app)
    -l, --logo-file <file>       specify a custom logo file (default: null)
    -c, --config-file <file>     specify a custom configuration file (default: app/lib/config.js)

Most options are self explanatory, but the following options warrant some further explanation:

--development-mode -d: This option starts a development server with a file watcher, and will automatically regenerate your docs when any of your spec or app files change.
--development-mode-live -D: This option starts a development server with a file watcher and live reload, and will automatically regenerate your docs when any of your spec or app files change.
--start-server -s: This option starts a production server without any development options enabled that serves the contents of your --target-dir.
--embeddable -e: This option lets you build a minimal version of the documentation without the HTML <body> tags, so you can embed Spectacle into your own website template. More info on custom builds here.
--app-dir -a: This option overrides the default directory which contains all the Handlebars templates, SCSS, and JavaScript source files. This option is useful for development because you can copy the contents of app to a remote location or a separate repo for custom builds.
--target-dir -t: This option specifies where the generated documentation HTML files will be output.

Custom Builds

The best option for building your own custom functionality into Spectacle is to fork Spectacle on GitHub, and make your own modifications in source. This way you can keep up to date by merging changes from the master branch, and your can also contribute your updates back to master by creating a Pull Request if you think they improve Spectacle somehow.

To fork Spectacle go to https://github.com/sourcey/spectacle, and press the 'Fork' button. Now you can git clone [email protected]:<yourname>/spectacle.git to make your own changes.

Alternatively, you can just copy the contents of app from the main repo which contains all the source files such as templates, stylesheets and JavaScripts. Now just pass the path to your custom app path to the CLI like so: spectacle -a /path/to/your/app your_swagger_api.json

Optimizing Your Workflow

Using an API spec to generate your docs has a number of great advantages, such as:

Maintain a single source: Save time by removing the need to maintain a separate API spec and API documentation.
No more out-of-date documentation: Your documentation will always be up-to-date with your API spec.
Be a better developer: Your entire API system will be more stable and robust when built around your spec as a single source of truth.

As developer we're always looking for ways to improve and optimize our workflow, and documentation is just the beginning. With a well written Swagger you can automate and generate many parts of your API system, such as:

Inline Code Generators: Generate your Swagger JSON or YAML from your source code comments.
Automate Testing: Automate testing for all your API endpoints.
Code Generation: Automatically generate client and server code from your spec.
Generate Documentation: Really?

For a list of open source Swagger based libraries in many languages check here: http://swagger.io/open-source-integrations/

Development

Testing

Testing is powered by Mocha/Chai, and automated testing is run via CircleCI.

At this stage, unit tests have not been written for all parts of the codebase. However, new code should be tested, and unit tests for the existing code will be added in the future.

Run npm test on the repository to start the automated tests. Some parts of testing can be configured using environment variables.

OFFLINE=true Some tests use HTTP connections to test giving Spectacle remote API specifications. Use OFFLINE=true to skip tests that require an internet connection.

Include environment variables before calling npm test. For example, OFFLINE mode can be enabled via OFFLINE=true npm test.

More Information

More info is available on the Spectacle homepage.

Please use the GitHub issue tracker if you have any ideas or bugs to report.

All contributions are welcome.

Good luck and enjoy Spectacle!

spectacle's People

Contributors

Stargazers

Watchers

Forkers

signiant tma-comms jayg4e earthspark kalafut dbrent-amazon roscopecoltran codelenny taarimalta jimmyjames robsman acorcoran-daon cholzberger ometria mikejholly botje treaston2 shirone danlopez00 magicking acima-credit etsfactory rjmanzer enjayem gtallen1187 alfonsom zakhenry risingstack aljp rilwanfit webtoolbox mbdyer ollionorg willgunn fmvilas mtaden coltonstapper tk guldner stefuhnee stefaniehansen dylangification andrewdonkin mdwheele svisser cfreyre lourheroes nijinaniyath haiderny glb qinfeng shepsy linebreaker g-d-g wolkabout jansteuer renatost ppasi07 jamesrwhite yyamano leihuagh a13e bchoang vinodkumarmarupu smrxt sergeypavlikhin sachingokal ashok2009it jasonl99 johz ppasi123 yetithefoot jcouto1959 easaw karsai5 sematext jonathanwalton720 safibaig kachyng puranjay6 seshi jgosm itssujeeth sobiech asrinagesh radoslawdabrowski kejace donaldpcook elifarley arunabhdas bernhardbauer zeyos lumamarigo noliran lethjakman erendira matthinz appscodelabs trieuan91 getmelisted

spectacle's Issues

Add compass/entities installation requirement in README.md

Hello,

It seems that "compass" must be installed using gem. If compass is not installed, I get this error message when generating my HTML :

Task error: { [Error: not found: compass] code: 'ENOENT' }

I also get an error message for the npm module "entities" :

Task error: { [Error: Cannot find module 'entities'] code: 'MODULE_NOT_FOUND' }

:-)

Not support remoute files

Application from npm is not supported remote files yet
Remote references not supported yet. Reference must start with "#" (but was tag.yml#/Tag/)
but in github exist version, that support it.
When will app update in npm?

Max number of characters doesn't appear when only max specified

Looks like there is a typo on this line

It should say maxLength instead of maxlength.

Currently the docs produced end up saying something like "(up to chars)" without having the number inserted. I believe this is due to the typo above.

Didn't think this small change was worth a pull request!

Development server does not update webpage

When I launch a development server using spectacle -d I expect the webserver to update the webpage when I make changes.

I can see the following messages in my console:

>> File "src\main\resources\swagger.yml" changed.

Running "clean:html" (clean) task
>> 2 paths cleaned.

Running "compile-handlebars:compile" (compile-handlebars) task

Running "predentation" task

Running "watch" task
Completed in 0.392s at Fri Dec 09 2016 10:55:42 GMT+0100 (Västeuropa, normaltid) - Waiting...

But the webpage is not updated. I refreshed the page after emptying my web browser's cache, but that did not help.

Can't run swagger json with dependent schema file

Hi Team,

I have swagger JSON file. I'm referring definitions from other schema file. How are we going to handle this in spectacle?

Synchronous CLI calls mix content

Hi,
I've been starting two Spectacle runs on different files at the same time in a build script, but some of the time (maybe one in four runs) one of the API pages is wrongly embedded in the other.

Censored as it's for a closed-source project (my apologies). Below "Documentation by Spectacle", the other document starts, with the title, schemes, and all routes.

I've paraphrased my Cakefile (CoffeeScript Make alternative).

{spawn, exec} = require "child-process-promise"
replace = require "replace-in-file"
chalk = require "chalk"

allSpectacle = (opts) ->
  spectacleDocs opts, "#{__dirname}/src1/api/api.yml", "#{__dirname}/doc/extra/src1/api"
  spectacleDocs opts, "#{__dirname}/src2/api/api.yml", "#{__dirname}/doc/extra/src2/api"

###
Build API docs via [spectacle](https://github.com/sourcey/spectacle)
@param [Object] opts the options passed to `cake`
@param [String] spec a path to the spec-file
@param [String] out a path to the output directory
###
spectacleDocs = (opts, spec, out) ->
  exec "$(npm bin)/spectacle #{spec} -t #{out}"
    .then ->
      replace
        files: "#{out}/index.html"
        replace: /(src|href)="\/\//g
        with: "$1=\"https://"
    .then ->
      replace
        files: "#{out}/index.html"
        replace: /(src|href)="\//g
        with: "$1=\""
    .then ->
      console.log chalk.green "Documented #{chalk.blue spec}"

I've changed my build file to run the two Spectacle compiles one after the other which may have fixed it (tested several of times), but it does slow the build down as Spectacle is one of the longer tasks.

Expand types in example requests/responses.

More of a feature request.

It would be awesome if the example response below expanded the meta key and showed all fields.

PUT/POST request bodies are rendered as "undefined"

Thanks for this great doc generator!

My Swagger spec has some POST and PUT body definitions like this:

/pm/project/docs/share:
    put:
      description: |+
        Share a Document with a user for translation in the
        Interface. This endpoint can also be used to unshare the
        Document.

      operationId: shareDocument
      parameters:
        - in: body
          name: body
          schema:
            type: object
            properties:
              doc_id:
                description: 'A unique Document identifier.'
                type: integer
              email:
                description: 'An email address.'
                type: string
              project_id:
                description: 'A unique Project identifier.'
                type: integer
              share:
                description: 'If false, then unshare the document.'
                type: boolean
            required:
              - project_id
              - doc_id
              - email
              - share

Here's the generated doc:

The request body is shown as "undefined". Is this a bug or a feature, or do I need to modify my Swagger spec?

Thanks.

Empty CSS

Using the tip in #10 does let things start, but I noticed that the stylesheets, whether statically generated or served via -d, are empty.

Missing helper: "json"

Hi,
I've been getting an error when using an example in a definition.

definitions:
  MyObject:
    type: object
    properties:
      myprop:
        type: string
    example:
      myprop: sample property value

I get the following error:

Running "compile-handlebars:compile" (compile-handlebars) task
Task error: { [Error: Missing helper: "json"]
  description: undefined,
  fileName: undefined,
  lineNumber: undefined,
  message: 'Missing helper: "json"',
  name: 'Error',
  number: undefined }

I tried adding a JSON handler (https://github.com/CodeLenny/spectacle/tree/json-handler), which stopped the above error and compiled my API docs, but included my example on the left. I expected it to appear on the right, like other examples do, and be syntax highlighted/monospace.

Is this intended?

Request example includes readonly properties

Isn't the intention with read-only properties to exclude them when creating/updating entities?

Objects and arrays

Hey, all.

I am trying to document an object containing an array as well as some other fields. Boiling it down to the bare minimum:

{
  "int": "integer",
  "array": [
    {
      "name": "string"
    }
  ]
}

I tried two ways:

swagger:  2.0

definitions:

  bad_properties_good_example:
    type: object
    properties:
      int:
        type: integer
      array:
        description: An array of dummys
        type: array
        items:
          $ref: '#/definitions/dummy'


  good_properties_bad_example:
    type: object
    properties:
      int:
        type: integer
      array:
        type: array
        $ref: '#/definitions/dummy'
            
  dummy:
    type: object
    properties:
      name:
        type: string

The former renders the example perfectly (as pasted in above), but the properties come out as:

bad_properties_good_example: object
PROPERTIES
int: integer
array: object[]
An array of dummys

...which isn't as useful as it could be.

good_properties_bad_example renders the properties as:

good_properties_bad_example: object
PROPERTIES
int: integer
array:  Array<dummy>

...which is great, especially since "dummy" is a link to its definition, but the example comes out as:

{
  "string": "string",
  "array": {
    "name": "string"
  }
}

...which is not.

I am new to swagger, so I am hoping that I am just doing it plumb wrong.

Thanks in advance.

Missing types in request/response examples

This might be a duplicate of issue #40

I have added an example file (all the way at the bottom of this issue) of a trivial API that has two GETs and two POSTs. This should give a total of 8 examples ( 4 * request and response ), of which one has rendered the expected example data. Among the issues are:

Array of entities rendered as [ null ]
6 examples missing entirely

This is when processing with spectacle-docs 0.7.5.

Have I created the yaml incorrectly here or is there perhaps a rendering/parsing-issue in spectacle?

swagger: 2.0
info:
  version: 1.0.0
  title: Sprockets and springs API
  description: >-
    Covering all your needs for sprockets and springs.
  contact:
    name: Sprocket!
    url: https://sprocketsprings.biz
    email: [email protected]
basePath: /api/v1
consumes:
  - application/json
produces:
  - application/json
paths:
  /sprockets:
    get:
      summary: Get list of sprockets
      description: >-
        This method returns all your sprockets. No exceptions, even Tiny Timmy is returned.
      operationId: getSprockets
      responses:
        200:
          description: A list of sprockets
          schema:
            type: array
            items:
              $ref: '#/definitions/Sprocket'
          
    post:
      summary: Create a new sprocket
      description: >-
        Use this method to create a new sprocket. Make sure it is a good sprocket. Remember what that bad one did to Uncle Jim.
      operationId: createSprocket
      parameters:
        - name: sprocket
          in: body
          description: The sprocket definition
          required: true
          schema:
            $ref: '#/definitions/NewSprocket'
      responses:
        '200':
          description: The new sprocket
          schema:
            $ref: '#/definitions/Sprocket'
  '/sprockets/{id}':
    get:
      summary: Get a specific sprocket
      description: >-
        Use this method when you need just that one special sprocket in your life. You will get one, and only one.
      operationId: getSprocket
      parameters:
        - name: id
          in: path
          description: numerical id of sprocket
          required: true
          type: integer
      responses:
        '200':
          description: Details of the sprocket
          schema:
            $ref: '#/definitions/Sprocket'
    post:
      summary: Update sprocket
      description: >-
        This is the method to use when you down on your luck and created a sprocket with the wrong specification.
      operationId: updateSprocket
      parameters:
        - name: id
          in: path
          description: numerical id of sprocket
          required: true
          type: integer
        - name: sprocket
          in: body
          description: Correct definition of sprocket
          required: true
          schema:
            $ref: '#/definitions/Sprocket'
      responses:
        '200':
          description: The newly updated sprocket definition
          schema:
            $ref: '#/definitions/Sprocket'
definitions:
  Sprocket:
    type: object
    allOf:
      - $ref: '#/definitions/NewSprocket'
      - required:
        - id
        properties:
          id:
            type: integer
            format: int32
            example: 201
  NewSprocket:
    type: object
    required:
      - name
      - radius
      - teeth
    properties:
      name:
        type: string
        example: My magical sprocket
      radius:
        type: float
        example: 12.0
      teeth:
        type: int
        example: 22
      description:
        type: string
        example: My dearest little sprocket. How I cherish it.

No support for `schema.$ref` in response block

When defining the resource block for an endpoint this seems to be parsed without crashing:

"responses": {
  "200": {
    "description": "The magic",
    "$ref": "#/definitions/Magic"
  }
}

This is also parsed without failing:

"responses": {
  "200": {
    "description": "The magic list",
    "schema": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Magic"
      }
    }
  }
}

This however fail spectacularly:

"responses": {
  "200": {
    "description": "pet response",
    "schema": {
      "$ref": "#/definitions/Pet"
    }
  }
}

The error is as follows:

Running "sass:foundation_scss" (sass) task

Running "concat:foundation_css" (concat) task
File public/docs/stylesheets/foundation.css created.

Running "sass:scss" (sass) task

Running "concat:css" (concat) task
File public/docs/stylesheets/spectacle.css created.

Running "cssmin:minify" (cssmin) task
>> 2 files created. 124.27 kB → 96.12 kB

Running "concat:js" (concat) task
File public/docs/javascripts/spectacle.js created.

Running "uglify:js" (uglify) task
>> 1 file created.

Running "clean:html" (clean) task
>> 1 path cleaned.

Running "compile-handlebars:compile" (compile-handlebars) task
Task error: [TypeError: Cannot convert undefined or null to object]

Running "predentation" task
Task error: { [Error: ENOENT: no such file or directory, open '/tmp/spectacle-181377bUV6f0YUJkd/api.html']
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/tmp/spectacle-181377bUV6f0YUJkd/api.html' }

Running "prettify:index" (prettify) task
>> Destination not written because dest file was empty.
All tasks complete
Unhandled rejection TypeError: Cannot convert undefined or null to object
    at Function.keys (native)
    at Object.common.formatExampleProp (node_modules/spectacle-docs/app/lib/common.js:91:11)
    at Object.common.formatExampleProp (node_modules/spectacle-docs/app/lib/common.js:88:16)
    at Object.common.formatExample (node_modules/spectacle-docs/app/lib/common.js:75:16)
    at Object.module.exports (node_modules/spectacle-docs/app/helpers/printExample.js:5:23)
    at Object.eval (eval at createFunctionContext (node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:254:23), <anonymous>:4:117)
    at main (node_modules/handlebars/dist/cjs/handlebars/runtime.js:173:32)
    at ret (node_modules/handlebars/dist/cjs/handlebars/runtime.js:176:12)
    at ret (node_modules/handlebars/dist/cjs/handlebars/compiler/compiler.js:525:21)
    at Object.invokePartial (node_modules/handlebars/dist/cjs/handlebars/runtime.js:273:12)
    at Object.invokePartialWrapper [as invokePartial] (node_modules/handlebars/dist/cjs/handlebars/runtime.js:68:39)
    at eval (eval at createFunctionContext (node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:254:23), <anonymous>:10:28)
    at prog (node_modules/handlebars/dist/cjs/handlebars/runtime.js:219:12)
    at execIteration (node_modules/handlebars/dist/cjs/handlebars/helpers/each.js:51:19)
    at Object.<anonymous> (node_modules/handlebars/dist/cjs/handlebars/helpers/each.js:80:11)
    at eval (eval at createFunctionContext (node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:254:23), <anonymous>:8:31)

This can be reproduced using the PetStore Expanded example file as provided by the OpenApi Initiative.

This was run with spectacle-docs 0.7.4 installed with npm.
The job definition in the package.json scrips-block looked as follows:

"build:docs": "mkdir -p public/docs; spectacle -t public/docs -f pet.html petstore-expanded.json",

Am I holding it wrong?

Incorrect data types for object properties

Hello,

When in JSON I have :
"properties": {
"platform": {
"type": "string",
"description": "a description"
},

In the HTML, I get "object" instead of "string" for the attribute "platform". The description and format fields are ignored.

Syntax error

Just installed from npm:

node -v
v0.12.15

"name": "spectacle-docs",
"version": "0.6.9",

When trying to process one file I am getting this error:

/usr/lib/node_modules/spectacle-docs/app/lib/config.js:16
                  [path.resolve(options.cacheDir, 'stylesheets/spectacle.css')
                  ^
SyntaxError: Unexpected token [
    at exports.runInThisContext (vm.js:73:16)
    at Module._compile (module.js:443:25)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Module.require (module.js:365:17)
    at require (module.js:384:17)
    at module.exports (/usr/lib/node_modules/spectacle-docs/index.js:29:18)
    at Object.<anonymous> (/usr/lib/node_modules/spectacle-docs/bin/spectacle.js:53:1)
    at Module._compile (module.js:460:26)

Any hint ?
Thanks,
Luis

Dockerize

Hi!

Would it be possible to hook your Github project's build pipeline into Docker Hub? We did it ourselves but it would be great to have a more "official" support from the project.

https://hub.docker.com/r/alexeiaguiar/spectacle/~/dockerfile/

Thank you

Docker image is not pushed to docker repository

When trying to use docker image:

docker pull sourcey/spectacle
Using default tag: latest
Error response from daemon: manifest for sourcey/spectacle:latest not found

Just pushing the image should work.

Make development mode fault-tolerant

Whenever you make a typo in your swagger.json file the development server crashes which is a tad annoying for development. More useful would be a visible representation of the stacktrace on the page so you know where the error is.

Example trace:

Running "watch" task
Completed in 0.195s at Thu Jun 22 2017 19:21:16 GMT+0200 (W. Europe Daylight Time) - Waiting...
module.js:590
    throw err;
    ^

SyntaxError: swagger.json: Unexpected string in JSON at position 17841
    at Object.parse (native)
    at Object.Module._extensions..json (module.js:587:27)
    at Module.load (module.js:487:32)
    at tryModuleLoad (module.js:446:12)
    at Function.Module._load (module.js:438:3)
    at Module.require (module.js:497:17)
    at require (internal/module.js:20:19)
    at loadData (npm\node_modules\spectacle-docs\index.js:53:46)
    at EventEmitter.<anonymous> (npm\node_modules\spectacle-docs\index.js:124:69)
    at EventEmitter.emit (npm\node_modules\spectacle-docs\node_modules\eventemitter2\lib\eventemitter2.js:339:22)
    at Gaze.<anonymous> (npm\node_modules\spectacle-docs\node_modules\grunt-contrib-watch\tasks\watch.js:145:25)
    at emitTwo (events.js:106:13)
    at Gaze.emit (events.js:191:7)
    at Gaze.emit (npm\node_modules\spectacle-docs\node_modules\gaze\lib\gaze.js:129:32)
    at npm\node_modules\spectacle-docs\node_modules\gaze\lib\gaze.js:415:16
    at StatWatcher._pollers.(anonymous function) (npm\node_modules\spectacle-docs\node_modules\gaze\lib\gaze.js:326:7)

To reproduce:

Create a valid swagger.json file
Start spectacle in develop mode (e.g. spectacle -d swagger.json)
Modify the swagger.json file to contain a syntax error

Refs to responses produces undefined in docs

When providing the following spec to spectacle, the response description and schema refs are not resolved and put into the docs. Instead it only says "undefined" in the documentation. I expected the Error definition to show in the docs.

/path:
  get:
    responses:
      200:
        schema:
          $ref: "#/definitions/Test"
      401:
        $ref: "#/responses/UnauthorizedResponse"
      404:
        $ref: "#/responses/NotFoundResponse"
      500:
        $ref: "#/responses/ServerErrorResponse"
definitions:
  Test:
    type: "string"   
  Error:
    type: "object"
    properties:
      code:
        type: "integer"
        format: "int32"
      type:
        type: "string"
      message:
        type: "string"
responses:
  NotFoundResponse:
    description: Not found.
    schema:
      $ref: "#/definitions/Error"
  UnauthorizedResponse:
    description: Unauthorized.
    schema:
      $ref: "#/definitions/Error"
  ServerErrorResponse:
    description: An unexpected error occurred.
    schema:
      $ref: "#/definitions/Error"

RAML Support

any plans to RAML support?

Right panel alignment issue on Safari (Version 9.1 (11601.5.17.1))

It works fine on Chrome (OSX) but on Safari I get the right panel mis-aligned (see attachment).

Cannot convert undefined or null to object

Possible related to #46 as the issue is the same but I still see this error when running build or development mode.

spectacle -l test/fixtures/cheese.png test/fixtures/petstore-expanded.json

All tasks complete
Unhandled rejection TypeError: Cannot convert undefined or null to object
    at Function.assign (<anonymous>)
    at /Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/app/lib/common.js:115:22
    at Array.forEach (native)
    at Object.formatExampleProp (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/app/lib/common.js:114:17)
    at Object.formatExampleProp (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/app/lib/common.js:102:18)
    at Object.formatExampleProp (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/app/lib/common.js:120:20)
    at Object.formatExample (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/app/lib/common.js:80:19)
    at Object.module.exports (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/app/helpers/printExample.js:5:23)
    at Object.eval [as main] (eval at createFunctionContext (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:254:23), <anonymous>:4:117)
    at main (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/runtime.js:175:32)
    at Object.ret (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/runtime.js:178:12)
    at Object.ret [as swagger/print-example] (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/compiler/compiler.js:526:21)
    at Object.invokePartialWrapper [as invokePartial] (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/runtime.js:72:46)
    at eval (eval at createFunctionContext (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/compiler/javascript-compiler.js:254:23), <anonymous>:10:28)
    at Object.prog [as fn] (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/runtime.js:221:12)
    at Object.<anonymous> (/Users/stephen/workspace/swagger-node/mydrive/node_modules/spectacle-docs/node_modules/handlebars/dist/cjs/handlebars/helpers/if.js:19:22)

Sub-menu links do not navigate

When I click an expanded sub-menu link, I expect to be navigated to that functionality. Nothing happens.

When the page is loaded, this JS error is printed multiple times in my console:
Uncaught TypeError: Cannot read property 'top' of undefined at HTMLAnchorElement.<anonymous> (http://localhost:4400/javascripts/spectacle.min.js:1:2089) at HTMLElement.dispatch (http://code.jquery.com/jquery-2.1.4.min.js:3:6466) at HTMLElement.r.handle (http://code.jquery.com/jquery-2.1.4.min.js:3:3241)

Edit:
Also it appears my parameter description tag is not applied to the documentation:

      parameters:
      - name: "interestRate"
        in: "query"
        required: true
        type: "number"
        minimum: 0.0
        description: "Test"

It just says (no description)

I am using a yml file to generate the documentation, perhaps that has something to do with my problems?

Couldn't get it working

When I run spectacle swagger.json I get this:

$ spectacle swagger.json 
module.js:471
    throw err;
    ^

Error: Cannot find module '/Users/andre/.nvm/versions/node/v6.9.1/lib/node_modules/spectacle-docs/swagger.json'
    at Function.Module._resolveFilename (module.js:469:15)
    at Function.Module._load (module.js:417:25)
    at Module.require (module.js:497:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (/Users/andre/.nvm/versions/node/v6.9.1/lib/node_modules/spectacle-docs/bin/spectacle-cli.js:50:16)
    at Module._compile (module.js:570:32)
    at Object.Module._extensions..js (module.js:579:10)
    at Module.load (module.js:487:32)
    at tryModuleLoad (module.js:446:12)
    at Function.Module._load (module.js:438:3)

/tmpl/.spectacle/index.html not found

I'm having this error when trying to run spectacle

Running "predentation" task
Task error: { [Error: ENOENT: no such file or directory, open '/tmp/.spectacle/index.html']
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/tmp/.spectacle/index.html' }

Support multiple example types

We are using Swashbuckle to generate swagger from a .net project, Given the sample swagger.json file, the example block is not rendered onto the webpage, only the generic schema:

The example block starts at line 30
swagger_example_issue.txt

For easy reference:
"responses": { "200": { "description": "Success", "schema": { "type": "array", "items": { "$ref": "#/definitions/BasicClient" } }, "examples": { "application/json": [ { "userId": "c12cfeef-0001-0010-0100-abb9e51deaf1", "firstName": "Bruce", "lastName": "Wayne", "email": "[email protected]", "homePhone": "555-555-5551", "cellPhone": "555-555-5550" }, { "userId": "d12cfeef-0001-0010-0100-abb9e51deaf2", "firstName": "George", "lastName": "Washington", "email": "[email protected]", "homePhone": "555-555-5553", "cellPhone": "555-555-5552" }, { "userId": "e12cfeef-0001-0010-0100-abb9e51deaf3", "firstName": "George", "lastName": "Washington", "email": "[email protected]", "homePhone": "555-555-5555", "cellPhone": "555-555-5554" } ] } } }
with BasicClient defined as
"BasicClient": { "type": "object", "properties": { "userId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string" }, "homePhone": { "type": "string" }, "cellPhone": { "type": "string" } } }

Disable file serving

The documentation specifies that --development-mode is false by default, but when I run spectacle with no options, it starts a web server and watches my swagger.yml file.

Also I did not find any way to disable it.

And thanks for this great package!

Auto reload/update browser on changes

When running in development mode it would be very helpful if the browser would automatically reload as soon as changes are detected.

Similar to how webpack does Hot Module Replacement: https://webpack.js.org/concepts/hot-module-replacement/

Ordering of operations alphabetically

The operations are grouped by tag in our swagger.json, but when displayed in spectacle, the operations appear in no particular order; how would we affect the order, for example alphabetically?

Exception when model have tree structure

I have model like that:

      "ChapterItemDto":{  
         "type":"object",
         "properties":{  
            "name":{  
               "type":"string"
            },
            "url":{  
               "type":"string"
            },
            "children":{  
               "type":"array",
               "items":{  
                  "$ref":"#/definitions/ChapterItemDto"
               },
               "readOnly":true
            }
         }
      },

Thus ChapterItemDto has children property. This property is an array of ChapterItemDto objects. For that construction when I execute spectacle I have following exception:

Running "compile-handlebars:compile" (compile-handlebars) task
Task error: RangeError: Maximum call stack size exceeded
    at String.lastIndexOf (native)
    at Object.resolveSchemaReference (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:159:19)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:101:17)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:119:20)
    at /usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:107:23
    at Array.forEach (native)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:106:35)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:102:18)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:119:20)
    at /usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:107:23
    at Array.forEach (native)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:106:35)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:102:18)
    at Object.formatExampleProp (/usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:119:20)
    at /usr/local/lib/node_modules/spectacle-docs/app/lib/common.js:107:23
    at Array.forEach (native)

Probably there is an infinite loop.

BTW: Thanks for great application!

Where is v0.6.7 source code?

Only v0.6.6 here https://github.com/sourcey/spectacle/blob/master/package.json#L3

Someone forget to push? Thanks for your awesome work 👍

example data is broken since 0.5

response examples do not work anymore. They're a copy of the definition, not an example

Cannot have more that one json file

I have tried having more than on configuration file because I have a lot of work to document and it would make sense to separate files for better management.

Code Highlighting Unreadable

I tried to include a code snippet, but found that the colors chosen for highlighting render strings nearly invisible.

And it's even harder to see at a normal resolution:

Would it be possible to change the color scheme to make snippets more readable? It looks like the grey background is assigned by foundation to all code blocks, but hljs is using a monoki theme for the foreground colors.

The code block is .lang-js. Would it be possible to select code[class^="lang-"], code[class*=" lang-"] and set the background color to a monoki background, or have some other fix?

<div class="doc-copy">
                <section class="swagger-operation-description"> <pre><code class="lang-js">echo(<span class="hljs-string">"Hello World"</span>);
</code></pre>
                  <!-- text removed -->
                    </section>
              </div>

Thanks!

Codegen timeline

I noticed the placeholders in the html for the codegen (curl, python, ruby, etc) that would mimic stripe. Is that a long term goal?

local install seems broken

$ npm install --save-dev spectacle-docs
$ ./node_modules/.bin/spectacle -d ./swagger.json  
                                                                                                  
>> Local Npm module "grunt-contrib-concat" not found. Is it installed?
>> Local Npm module "grunt-contrib-uglify" not found. Is it installed?
>> Local Npm module "grunt-contrib-compass" not found. Is it installed?
>> Local Npm module "grunt-contrib-cssmin" not found. Is it installed?
>> Local Npm module "grunt-contrib-watch" not found. Is it installed?
>> Local Npm module "grunt-contrib-clean" not found. Is it installed?
>> Local Npm module "grunt-contrib-copy" not found. Is it installed?
>> Local Npm module "grunt-contrib-connect" not found. Is it installed?
>> Local Npm module "grunt-compile-handlebars" not found. Is it installed?
Task error: Error: Task "compass:scss" not found.

Parameter description is not showing

I have a swagger.yml file that contains:

...
/some/endpoint:
    get:
      tags:
      - "My Tag"
      summary: "This is an endpoint"
      description: "It has an end on its point"
      operationId: "someEndpoint"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "aParameter"
        description: "This is not printed"
        in: "query"
        required: true
        type: "integer"
        minimum: 1.0
        format: "int32"
...

When I look at the webpage, it says (no description).

Am I doing something wrong?

Missing dependencies?

Completely vanilla install, no extras.

$ spectacle swagger.json 
Running "compass:scss" (compass) task
Task error: { [Error: not found: compass] code: 'ENOENT' }

Running "concat:css" (concat) task
File /Users/andybaird/src/threads-api-docs/public/stylesheets/spectacle.css created.

Running "cssmin:minify" (cssmin) task
>> 1 file created. 0 B → 0 B

Running "compass:foundation_scss" (compass) task
Task error: { [Error: not found: compass] code: 'ENOENT' }

Running "concat:foundation_css" (concat) task
File /Users/andybaird/src/threads-api-docs/public/stylesheets/foundation.css created.

Running "concat:js" (concat) task
File /Users/andybaird/src/threads-api-docs/public/javascripts/spectacle.js created.

Running "uglify:js" (uglify) task
>> 1 file created.

Running "clean:html" (clean) task
>> 0 paths cleaned.

Running "compile-handlebars:compile" (compile-handlebars) task
Task error: { [Error: Cannot find module 'entities'] code: 'MODULE_NOT_FOUND' }

Running "predentation" task
Task error: { [Error: ENOENT: no such file or directory, open '/var/folders/x4/ddpswrbj12q6cvls6qbs_x3c0000gn/T/.spectacle/index.html']
  errno: -2,
  code: 'ENOENT',
  syscall: 'open',
  path: '/var/folders/x4/ddpswrbj12q6cvls6qbs_x3c0000gn/T/.spectacle/index.html' }
All tasks complete

$ spectacle --version
0.4.2

It appears I'm missing compass and a module called "entities" but I don't see anything in the readme about either (unless I missed it)

produces/consumes from paths: is not shown

Path produces/consumes MIME type's are not displayed anywhere on the rendered page:
Example:

paths:
  /endpoint/v1:
    post:
      tags:
      - "my_endpoint"
      summary: "summary"
      description: "desc"
      consumes:
      - "application/json"
      produces:
      - "application/json"

The application/json is not shown in the rendered docs.
Thx!

Generic List transforms to "ungeneric" array

It seems like there is a problem regarding Java generics in combination with Spectacle.

If I create an annotation like this:

@ApiModelProperty(dataType = "List[com.example.MyClass]")
private List<MyClass> myClasses;

It will create a generic documentation in Swagger:


myClasses (optional)
array[MyClass]

But when I tries the same in Spectacle it transforms to an "ungeneric" object array:

myClasses: object[]

Doesn't handle links to parameter references

When you have

"schema": {
    "$ref": "#/definitions/User"
}

then it will link to the User definition at the bottom. But if you have

"parameters": [{
    "$ref": "#/parameters/username"
}]

then the link is still created but because the parameter definitions are never added, there is nothing to link to. Also the description field doesn't get populated from the referenced parameter.

Does not show enum data in response

In Response
It only shows status code and description + returned data
It does not show enums defined there only

Example:

Should show this:

string , x ∈ { "Db not working","Redis not working" }

"/aws/healthcheck": {
      "get": {
        "tags": [
          "Healthcheck"
        ],
        "summary": "Returns service status",
        "description": "Checks if our APIs are online",
        "operationId": "getStatus",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "All services online"
          },
          "500": {
            "description": "Something is wrong",
            "schema": {
              "type": "string",
              "enum": [
                "Db not working",
                "Redis not working"
              ]
            }
          }
        }
      }
    }

Definitions are not correctly parsed

This definition:

"Company": {
            "type": "object",
            "properties": {
                "_id": {
                    "type": "string",
                    "description": "The id of the company."
                },
                "name": {
                    "type": "string",
                    "description": "The name of the company."
                },
                "address": {
                    "type": "string",
                    "description": "Invoice address of the company"
                }
            }
        },

is parsed as:

I've used swagger editor to create the definition and it works properly there

Incorrect example with `type` in `schema`

There's an id field in the body, and it's an integer type. (Swagger 2.0)

Everything's normal in Swagger Editor.

But Spectacle treats the schema as the example body, which is incorrect.

It should be:

{
    "id": "integer"
}

{
    "id": 152
}

Show defaults for parameters

When a parameter is not required, the default value is rather important, but is not shown in the rendered specification. Hopefully this is trivial to add, but my JS foo is nonexistent so I can't do this myself.

paths:
  /orders:
    get:
      summary: 'List orders'
      parameters:
      - name: OnlyOpen
        in: header
        type: boolean
        description: Only return open orders?
        default: true