swagger-magic

This module configures an express app with all the swagger magic

Usage no npm install needed!

<script type="module">
  import swaggerMagic from 'https://cdn.skypack.dev/swagger-magic';
</script>

README

Install

npm install swagger-magic --save

Credit

This module inspired by Apigee-127's awesome volos swagger and a127-magic :)

Documentation

This module combins swagger-tools and auth handling in order to provide express server based on swagger out of the box.

In addition to the securityDefinitions in the swagger spec, this module expects optional x-invalidateTokenUrl property in order to provide token invalidation as well.

Example:

securityDefinitions:
  oauth2:
    type: oauth2
    scopes:
        read: "allow read"
    flow: password
    tokenUrl: "/auth/token"
    x-invalidateTokenUrl: "/auth/invalidate"

Currently, the swagger-magic supports oauth2 with password flow only.

Check out the test in order to understand better how the swagger-magic expects the options to be provided.

swagger-magic

This module configures an express app with all the swagger magic

Params

  • swaggerObject Object - swagger spec representing the api
  • options Object - options
    • [token] Object - implementation of the swagger-magic-token-interface. required if securityDefinitions defined in the swagger spec
    • [auth] Object - implementation of the swagger-magic-auth-interface. required if securityDefinitions defined in the swagger spec
    • [socialAuth] Object - implementation of the swagger-magic-social-auth-interface. required if x-swagger-magic-social defined in the swagger spec
    • [controllers] Object - controllers where every key is the controller's name and the value is an object containing all it's methods
    • [ui] Object - options to be passed to the swagger-ui middleware
    • [errorConverter] function - error converter to the swagger-magic error format
    • [validateResponse] Boolean - indicates if the swagger-validator should validate the response.
    • [useStubs] Boolean - Whether or not to stub missing controllers and methods
  • callback function - a callback to call when the configuration finishes.

Example

    var magic = require("swagger-magic");

    magic(swaggerObject, options, function (app) {
        app.listen(3001);
    });