Beautiful static documentation generator for OpenAPI/Swagger 2.0

Overview

Spectacle

The gentleman at REST

CircleCI

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


Demo Screenshot


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 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 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]: /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!

Comments
  • Added support for referencing remote schemas

    Added support for referencing remote schemas

    Hi @auscaster,

    I've been exploring support for referencing remote files. I've managed to hack support in, but it's very ugly.

    Given that you're more familiar with the code base, I wondered if you'd have an opinion of the cleanest way to get the data needed to read remote files.

    It looks like the only things that common.resolveSchemaReference needs is a path to the current file (to resolve relative references) and options to pass along to /lib/preprocessor.

    • ~~Clean relative references~~
    • ~~Clean passing options for preprocessor.~~

    I haven't tested deep file references, but OpenAPI's petstore-seperate is working for me (although I did flatten the file paths, and should test on the original).

    screenshot from 2017-03-02 19-48-36

    • [x] Build doesn't error out when a remote file is referenced
    • [x] Response examples from remote files are included

    Task list has been re-organized since the first message in this PR. The below list is the current state of the PR. Please note that many changes were directly implemented, and never added to the list.

    • Tests

      • [x] Test complex paths
      • [x] Test deep file references
      • [x] Test files requested over HTTP
      • [x] Test "contexts"
      • [ ] Add failure-case tests (replaceReference, replaceRefs)
      • [x] Document testing in README
      • [x] Add remote reference inside cheesestore.json
    • Remote Schema Evaluation

      • [x] Remote URLs could be cached to provide better performance (if not desired, remove TODO comment on fetchReference)
      • [x] Relative URLs don't work with Remote URLs
      • [x] Local paths in external files aren't handled (see replaceRefs)
      • "reference contexts" (utilities that recognize "/responses/[code]/schema" as something to insert into "/definitions/[...]"
        • ~~Add additional contexts~~ (2nd PR)
        • ~~Make contexts optional~~ (2nd PR)
    • Tags

      • [x] Handle tags as needed
    • UI

      • ~~Tweak names to remove paths? (in definitions, Pet.yml -> Pet, defs.yml#/things/Pet -> Pet)~~ (2nd PR)
      • ~~Add "Imported From"~~ (2nd PR)
      • ~~Add tests?~~
      • [x] Schema definitions aren't copied into the main page

    Random issues noted that should be checked at the end:

    • [ ] Parameter definitions aren't working
    • [ ] Path ordering is done before paths in external references have been added
    opened by CodeLenny 54
  • objects within definitions are not shown properly in the docs

    objects within definitions are not shown properly in the docs

    Problem: When a definition has a property that is an object, this property is shown as "object" with none of its own properties outputted to the doc.

    Example doc fragment:

    ...
          challenges:
            type: object
            properties:
              total:
                description: Total number of challenges
                type: integer
              completed:
                description: Number of challenges completed by participant
                type: integer
    ...
    

    Renders to: challenges: object

    Expected behaviour:

    Sub-properties to be documented also.

    opened by leaanthony 16
  • The implementation option must be passed to the Sass task

    The implementation option must be passed to the Sass task

    nvm use 8.10
    npm install spectacle-docs
    ./node_modules/.bin/spectacle swagger.yml
    

    produces

    Running "sass:foundation_scss" (sass) task
    Fatal error: The implementation option must be passed to the Sass task.
    

    swagger.yml reports no error on editor.swagger.io.

    opened by EgidioCaprino 15
  • Code Highlighting Unreadable

    Code Highlighting Unreadable

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

    screenshot from 2017-01-06 16-08-04

    And it's even harder to see at a normal resolution: screenshot from 2017-01-06 16-07-43

    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!

    opened by CodeLenny 14
  • Doesn't handle links to parameter references

    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.

    enhancement help wanted 
    opened by beardedlinuxgeek 12
  • Grunt cannot find task `sass:foundation_scss` in v0.9.13

    Grunt cannot find task `sass:foundation_scss` in v0.9.13

    I'm trying to generate documentation for a Swagger JSON generated using swagger-php, and am using the following command (it's a local npm install since I have to include it in version control, but the same thing happens when I install spectacle globally):

    node node_modules/spectacle-docs/bin/spectacle.js -d "./docs/swagger.json" -t "./docs/html"
    

    Schema:

    {
        "swagger": "2.0",
        "info": {
            "title": "Control Panel API",
            "version": "1.0"
        },
        "schemes": [
            "https"
        ],
        "paths": {
            "/container/{id}": {
                "get": {
                    "summary": "Returns information about a container using the provided identification",
                    "operationId": "findContainerById",
                    "produces": [
                        "application/json"
                    ],
                    "parameters": [
                        {
                            "parameter": "id",
                            "name": "id",
                            "in": "path",
                            "description": "The ID of the container",
                            "required": true,
                            "type": "integer"
                        }
                    ],
                    "responses": {
                        "200": {
                            "description": "A successful response returns the information about the container",
                            "schema": {
                                "properties": {
                                    "error": {
                                        "description": "Returns information about a specific container using provided #ID",
                                        "type": "boolean",
                                        "default": "false"
                                    },
                                    "payload": {
                                        "description": "Returns information about a specific container using provided #ID",
                                        "properties": {
                                            "id": {
                                                "description": "Returns information about a specific container using provided #ID",
                                                "type": "integer"
                                            },
                                            "instances": {
                                                "description": "An object of the instances in this container, with instance ID as the key",
                                                "type": "object"
                                            }
                                        },
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    },
                    "security": [
                        "bearer"
                    ]
                }
            }
        },
        "definitions": {},
        "securityDefinitions": {
            "bearer": {
                "type": "apiKey",
                "description": "The API token is provided to the client during authentication",
                "in": "header"
            }
        }
    }
    

    It gives me the following output:

    spectacle docs/swagger.json -t docs/html
    Loading "sass.js" tasks...ERROR
    >> Error: ENOENT: no such file or directory, scandir '/media/sf_goyal.115/webappapi/node_modules/node-sass/vendor'
    Task error: Error: Task "sass:foundation_scss" not found.
        at Task.run (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:179:28)
        at Object.thisTask.fn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/grunt/task.js:82:16)
        at Object.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:301:30)
        at Task.runTaskFn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:251:24)
        at Task.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:300:12)
        at Task.start (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:309:5)
        at module.exports (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/index.js:169:16)
        at Object.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/bin/spectacle.js:35:1)
        at Module._compile (module.js:635:30)
        at Object.Module._extensions..js (module.js:646:10)
        at Module.load (module.js:554:32)
        at tryModuleLoad (module.js:497:12)
        at Function.Module._load (module.js:489:3)
        at Function.Module.runMain (module.js:676:10)
        at startup (bootstrap_node.js:187:16)
        at bootstrap_node.js:608:3
    Task error: Error: Task "sass:scss" not found.
        at Task.run (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:179:28)
        at Object.thisTask.fn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/grunt/task.js:82:16)
        at Object.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:301:30)
        at Task.runTaskFn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:251:24)
        at Task.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:300:12)
        at Task.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:230:9)
        at Task.runTaskFn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:257:7)
        at Task.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:300:12)
        at Task.start (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:309:5)
        at module.exports (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/index.js:169:16)
        at Object.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/bin/spectacle.js:35:1)
        at Module._compile (module.js:635:30)
        at Object.Module._extensions..js (module.js:646:10)
        at Module.load (module.js:554:32)
        at tryModuleLoad (module.js:497:12)
        at Function.Module._load (module.js:489:3)
    
    Running "concat:js" (concat) task
    File docs/html/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
    Unhandled rejection Error: Task "sass:foundation_scss" not found.
        at Task.run (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:179:28)
        at Object.thisTask.fn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/grunt/task.js:82:16)
        at Object.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:301:30)
        at Task.runTaskFn (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:251:24)
        at Task.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:300:12)
        at Task.start (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/node_modules/grunt/lib/util/task.js:309:5)
        at module.exports (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/index.js:169:16)
        at Object.<anonymous> (/home/echofoxxx/.nvm/versions/node/v8.9.2/lib/node_modules/spectacle-docs/bin/spectacle.js:35:1)
        at Module._compile (module.js:635:30)
        at Object.Module._extensions..js (module.js:646:10)
        at Module.load (module.js:554:32)
        at tryModuleLoad (module.js:497:12)
        at Function.Module._load (module.js:489:3)
        at Function.Module.runMain (module.js:676:10)
        at startup (bootstrap_node.js:187:16)
        at bootstrap_node.js:608:3
    
    
    Running "predentation" task
    
    Running "prettify:index" (prettify) task
    >> File "docs/html/index.html" prettified.
    All tasks complete
    

    I'm guessing there's something wrong with the versioning of grunt-sass? Or is it something with my installation?

    opened by abhidvnt 11
  • Synchronous CLI calls mix content

    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.

    spectacle-embedded-obs

    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.

    opened by CodeLenny 9
  • Objects and arrays

    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.

    opened by andrewdonkin 8
  • How to show response examples?

    How to show response examples?

    I can't find how to make the response samples appear in the generated output.

    My Open API file is:

    "v1/user_profiles/{id}": {
          "get": {
            "tags": [
              "User profile"
            ],
            "summary": "Get user profile",
            "description": "Gets all the user profile. The user needs to be authorized for this operation (own profile or admin).",
            "consumes": [
              "application/json"
            ],
            "produces": [
              "application/json"
            ],
            "parameters": [
              {
                "name": "id",
                "in": "path",
                "description": "",
                "required": true,
                "type": "integer"
              }
            ],
            "responses": {
              "200": {
                "description": "Success",
                "schema": {
                  "description": "",
                  "type": "object",
                  "properties": {
                  }
                },
                "headers": {
                },
                "examples": {
                  "application/json": {
                    "id": 1,
                    "firstname": "Otis",
                    "lastname": "Kertzmann",
                    "user_id": 1
                  }
                }
              }
            },
            "deprecated": false,
            "security": [
    
            ]
          }
    

    So the example is in there. But when I build with spectacle, it does not show in the output. I understand only the schema shows up (in this case nothing, so can't see the returned output).

    Thanks for the great work!

    opened by qortex 7
  • if a path's summary contains a period, it's used for the link and title

    if a path's summary contains a period, it's used for the link and title

    spectacle version 0.9.13, swagger spec version 2.0 (generated by goswagger 0.13.0)

    I noticed something strange when I ran spectacle against my swagger json. In the left sidebar some of my endpoints were listed by their method and endpoint, and some were listed by their summary. I did an audit and realized the pattern: those with a period "." in their summary were the ones listed by their summary.

    sidebar

    Further, the main content would display the summary as the title, and have a "Path" block under it.

    unexpected content

    The behavior I expect is for the title to be the method and path, and there to be a Description block under it.

    expected content

    opened by ghost 6
  • How to run this app on local machine and github pages aswell

    How to run this app on local machine and github pages aswell

    E:\APIDoc\spectacle-master\spectacle-master>spectacle spectacle -s module.js:471 throw err; ^

    Error: Cannot find module 'E:\APIDoc\spectacle-master\spectacle-master\spectacle ' 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 loadData (C:\Users\miracle\AppData\Roaming\npm\node_modules\spectacle-doc s\index.js:53:46) at module.exports (C:\Users\miracle\AppData\Roaming\npm\node_modules\spectac le-docs\index.js:56:70) at Object. (C:\Users\miracle\AppData\Roaming\npm\node_modules\spe ctacle-docs\bin\spectacle.js:35:1) 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) at Module.runMain (module.js:604:10) at run (bootstrap_node.js:390:7) at startup (bootstrap_node.js:150:9) at bootstrap_node.js:505:3

    I got this error on my machine.

    opened by vinodkumarmarupu 6
  • Bump qs from 6.5.2 to 6.5.3

    Bump qs from 6.5.2 to 6.5.3

    Bumps qs from 6.5.2 to 6.5.3.

    Changelog

    Sourced from qs's changelog.

    6.5.3

    • [Fix] parse: ignore __proto__ keys (#428)
    • [Fix] utils.merge`: avoid a crash with a null target and a truthy non-array source
    • [Fix] correctly parse nested arrays
    • [Fix] stringify: fix a crash with strictNullHandling and a custom filter/serializeDate (#279)
    • [Fix] utils: merge: fix crash when source is a truthy primitive & no options are provided
    • [Fix] when parseArrays is false, properly handle keys ending in []
    • [Fix] fix for an impossible situation: when the formatter is called with a non-string value
    • [Fix] utils.merge: avoid a crash with a null target and an array source
    • [Refactor] utils: reduce observable [[Get]]s
    • [Refactor] use cached Array.isArray
    • [Refactor] stringify: Avoid arr = arr.concat(...), push to the existing instance (#269)
    • [Refactor] parse: only need to reassign the var once
    • [Robustness] stringify: avoid relying on a global undefined (#427)
    • [readme] remove travis badge; add github actions/codecov badges; update URLs
    • [Docs] Clean up license text so it’s properly detected as BSD-3-Clause
    • [Docs] Clarify the need for "arrayLimit" option
    • [meta] fix README.md (#399)
    • [meta] add FUNDING.yml
    • [actions] backport actions from main
    • [Tests] always use String(x) over x.toString()
    • [Tests] remove nonexistent tape option
    • [Dev Deps] backport from main
    Commits
    • 298bfa5 v6.5.3
    • ed0f5dc [Fix] parse: ignore __proto__ keys (#428)
    • 691e739 [Robustness] stringify: avoid relying on a global undefined (#427)
    • 1072d57 [readme] remove travis badge; add github actions/codecov badges; update URLs
    • 12ac1c4 [meta] fix README.md (#399)
    • 0338716 [actions] backport actions from main
    • 5639c20 Clean up license text so it’s properly detected as BSD-3-Clause
    • 51b8a0b add FUNDING.yml
    • 45f6759 [Fix] fix for an impossible situation: when the formatter is called with a no...
    • f814a7f [Dev Deps] backport from main
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
  • Bump grunt from 1.4.1 to 1.5.3

    Bump grunt from 1.4.1 to 1.5.3

    Bumps grunt from 1.4.1 to 1.5.3.

    Release notes

    Sourced from grunt's releases.

    v1.5.3

    • Merge pull request #1745 from gruntjs/fix-copy-op 572d79b
    • Patch up race condition in symlink copying. 58016ff
    • Merge pull request #1746 from JamieSlome/patch-1 0749e1d
    • Create SECURITY.md 69b7c50

    https://github.com/gruntjs/grunt/compare/v1.5.2...v1.5.3

    v1.5.2

    • Update Changelog 7f15fd5
    • Merge pull request #1743 from gruntjs/cleanup-link b0ec6e1
    • Clean up link handling 433f91b

    https://github.com/gruntjs/grunt/compare/v1.5.1...v1.5.2

    v1.5.1

    • Merge pull request #1742 from gruntjs/update-symlink-test ad22608
    • Fix symlink test 0652305

    https://github.com/gruntjs/grunt/compare/v1.5.0...v1.5.1

    v1.5.0

    • Updated changelog b2b2c2b
    • Merge pull request #1740 from gruntjs/update-deps-22-10 3eda6ae
    • Update testing matrix 47d32de
    • More updates 2e9161c
    • Remove console log 04b960e
    • Update dependencies, tests... aad3d45
    • Merge pull request #1736 from justlep/main fdc7056
    • support .cjs extension e35fe54

    https://github.com/gruntjs/grunt/compare/v1.4.1...v1.5.0

    Changelog

    Sourced from grunt's changelog.

    v1.5.3 date: 2022-04-23 changes: - Patch up race condition in symlink copying. v1.5.2 date: 2022-04-12 changes: - Unlink symlinks when copy destination is a symlink. v1.5.1 date: 2022-04-11 changes: - Fixed symlink destination handling. v1.5.0 date: 2022-04-10 changes: - Updated dependencies. - Add symlink handling for copying files.

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
  • Bump minimist from 1.2.5 to 1.2.6

    Bump minimist from 1.2.5 to 1.2.6

    Bumps minimist from 1.2.5 to 1.2.6.

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
  • Update jquery and leverage SRI

    Update jquery and leverage SRI

    Hi there,

    I have a few suggestions for improving the security of the third-party jquery script loaded here: https://github.com/sourcey/spectacle/blob/master/app/views/partials/layout/head.hbs#L9

    • Upgrade jquery to the latest version - there are currently known CVEs in 2.1.4: https://snyk.io/test/npm/jquery/2.1.4
    • Leverage SRI on the script attribute: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity

    These security issues were noted in a website generated by this tool.

    opened by rc-mattschwager 0
  • Bump node-sass from 6.0.1 to 7.0.0

    Bump node-sass from 6.0.1 to 7.0.0

    Bumps node-sass from 6.0.1 to 7.0.0.

    Release notes

    Sourced from node-sass's releases.

    v7.0.0

    Breaking changes

    Features

    Dependencies

    Community

    • Remove double word "support" from documentation (@​pzrq, #3159)

    Misc

    Supported Environments

    OS Architecture Node
    Windows x86 & x64 12, 14, 16, 17
    OSX x64 12, 14, 16, 17
    Linux* x64 12, 14, 16, 17
    Alpine Linux x64 12, 14, 16, 17
    FreeBSD i386 amd64 12, 14

    *Linux support refers to major distributions like Ubuntu, and Debian

    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
  • Bump marked from 2.1.3 to 4.0.10

    Bump marked from 2.1.3 to 4.0.10

    Bumps marked from 2.1.3 to 4.0.10.

    Release notes

    Sourced from marked's releases.

    v4.0.10

    4.0.10 (2022-01-13)

    Bug Fixes

    • security: fix redos vulnerabilities (8f80657)

    v4.0.9

    4.0.9 (2022-01-06)

    Bug Fixes

    v4.0.8

    4.0.8 (2021-12-19)

    Bug Fixes

    v4.0.7

    4.0.7 (2021-12-09)

    Bug Fixes

    v4.0.6

    4.0.6 (2021-12-02)

    Bug Fixes

    v4.0.5

    4.0.5 (2021-11-25)

    Bug Fixes

    • table after paragraph without blank line (#2298) (5714212)

    v4.0.4

    4.0.4 (2021-11-19)

    ... (truncated)

    Commits
    • ae01170 chore(release): 4.0.10 [skip ci]
    • fceda57 🗜️ build [skip ci]
    • 8f80657 fix(security): fix redos vulnerabilities
    • c4a3ccd Merge pull request from GHSA-rrrm-qjm4-v8hf
    • d7212a6 chore(deps-dev): Bump jasmine from 4.0.0 to 4.0.1 (#2352)
    • 5a84db5 chore(deps-dev): Bump rollup from 2.62.0 to 2.63.0 (#2350)
    • 2bc67a5 chore(deps-dev): Bump markdown-it from 12.3.0 to 12.3.2 (#2351)
    • 98996b8 chore(deps-dev): Bump @​babel/preset-env from 7.16.5 to 7.16.7 (#2353)
    • ebc2c95 chore(deps-dev): Bump highlight.js from 11.3.1 to 11.4.0 (#2354)
    • e5171a9 chore(release): 4.0.9 [skip ci]
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    • @dependabot use these labels will set the current labels as the default for future PRs for this repo and language
    • @dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language
    • @dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language
    • @dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

    You can disable automated security fix PRs for this repo from the Security Alerts page.

    dependencies 
    opened by dependabot[bot] 0
SqlAlchemy Flask-Restful Swagger Json:API OpenAPI

SAFRS: Python OpenAPI & JSON:API Framework Overview Installation JSON:API Interface Resource Objects Relationships Methods Custom Methods Class Method

Thomas Pollet 361 Nov 16, 2022
Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

drf-yasg - Yet another Swagger generator Generate real Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API. Compatible with Django Res

Cristi Vîjdea 3k Dec 31, 2022
Test utility for validating OpenAPI documentation

DRF OpenAPI Tester This is a test utility to validate DRF Test Responses against OpenAPI 2 and 3 schema. It has built-in support for: OpenAPI 2/3 yaml

snok 106 Jan 5, 2023
API spec validator and OpenAPI document generator for Python web frameworks.

API spec validator and OpenAPI document generator for Python web frameworks.

1001001 249 Dec 22, 2022
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 831 Dec 27, 2022
Literate-style documentation generator.

888888b. 888 Y88b 888 888 888 d88P 888 888 .d8888b .d8888b .d88b. 8888888P" 888 888 d88P" d88P" d88""88b 888 888 888

Pycco 808 Dec 27, 2022
Documentation generator for C++ based on Doxygen and mosra/m.css.

mosra/m.css is a Doxygen-based documentation generator that significantly improves on Doxygen's default output by controlling some of Doxygen's more unruly options, supplying it's own slick HTML+CSS generation and adding a fantastic live search feature.

Mark Gillard 109 Dec 7, 2022
Markdown documentation generator from Google docstrings

mkgendocs A Python package for automatically generating documentation pages in markdown for Python source files by parsing Google style docstring. The

Davide Nunes 44 Dec 18, 2022
Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.

Flask-Rebar Flask-Rebar combines flask, marshmallow, and swagger for robust REST services. Features Request and Response Validation - Flask-Rebar reli

PlanGrid 223 Dec 19, 2022
A swagger tool for tornado, using python to write api doc!

SwaggerDoc About A swagger tool for tornado, using python to write api doc! Installation pip install swagger-doc Quick Start code import tornado.ioloo

aaashuai 1 Jan 10, 2022
Sane and flexible OpenAPI 3 schema generation for Django REST framework.

drf-spectacular Sane and flexible OpenAPI 3.0 schema generation for Django REST framework. This project has 3 goals: Extract as much schema informatio

T. Franzel 1.4k Jan 8, 2023
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 2, 2023
API Documentation for Python Projects

API Documentation for Python Projects. Example pdoc -o ./html pdoc generates this website: pdoc.dev/docs. Installation pip install pdoc pdoc is compat

mitmproxy 1.4k Jan 7, 2023
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 4, 2023
Project documentation with Markdown.

MkDocs Project documentation with Markdown. View the MkDocs documentation. Project release notes. Visit the MkDocs wiki for community resources, inclu

MkDocs 15.6k Jan 2, 2023
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 440 Jan 6, 2023
Your Project with Great Documentation.

Read Latest Documentation - Browse GitHub Code Repository The only thing worse than documentation never written, is documentation written but never di

Timothy Edmund Crosley 809 Dec 28, 2022
:blue_book: Automatic documentation from sources, for MkDocs.

mkdocstrings Automatic documentation from sources, for MkDocs. Features Python handler features Requirements Installation Quick usage Features Languag

Timothée Mazzucotelli 1.1k Dec 31, 2022
Run `black` on python code blocks in documentation files

blacken-docs Run black on python code blocks in documentation files. install pip install blacken-docs usage blacken-docs provides a single executable

Anthony Sottile 460 Dec 23, 2022