Skip to main content

@gasket/plugin-swagger

Gasket plugin for working with Swagger specs, and uses swagger-ui-express to serve Swagger UI docs with Express and uses [fastify-swagger] to serve Swagger UI docs with Fastify.

Installation​

npm i @gasket/plugin-swagger

Update your gasket file plugin configuration:

// gasket.js

+ import pluginSwagger from '@gasket/plugin-swagger';

export default makeGasket({
  plugins: [
+   pluginSwagger
  ]
});

Configuration​

  • swagger - (object) The base gasket.config object.
    • definitionFile - (string) Target swagger spec file, either json or yaml. (Default: 'swagger.json')
    • apiDocsRoute - (string) Route to Swagger UI (Default: '/api-docs')
    • jsdoc - (object) If set, the definitionFile will be generated based on JSDocs in the configured files. See the swagger-jsdocs options for what is supported.
    • ui - (object) Optional custom UI options. See swagger-ui-express options for what is supported.
    • uiConfig - (object) Optional custom UI options. Only for use with Fastify. See @fastify/swagger-ui options for what is supported.

Example from JSDocs​

By specifying the swagger.jsdocs options in the gasket.js, the Swagger definition file will be generated with npm run build. It can be output to either a JSON (default) or YAML file.

// gasket.js

export default makeGasket({
  swagger: {
    jsdoc: {
      definition: {
        openapi: '3.0.0',           // Specification (optional, defaults to swagger: '2.0')
        info: {
          title: 'Theme API',       // Title (required)
          version: '1.0.0'          // Version (required)
        }
      },
      apis: ['api.js'] // Glob path to API Docs
    },
    definitionFile: 'swagger.json', // Default
    apiDocs: '/api-docs'            // Default
  }
});

Example from YAML​

In this example, the Swagger spec will not be generated, but rather demonstrates how it can be hand-crafted via YAML file.

// gasket.js

export default makeGasket({
  swagger: {
    definitionFile: 'swagger.yaml'
  }
});

License​

MIT