egg-swagger-jsdoc

Install

$ npm i egg-swagger-jsdoc --save

Usage

// {app_root}/config/plugin.js
exports.swagger = {
  enable: true,
  package: 'egg-swagger-jsdoc',
};

// {app_root}/config/config.default.js
const swaggerUIAbsolutePath = require('egg-swagger-jsdoc').absolutePath();
const path = require('path');

module.exports = appInfo => {

  /**
   * built-in config
   * @type {Egg.EggAppConfig}
   **/
  const config = exports = {};


  // If the egg-static default configuration is not overridden,
  // the default swagger-ui path is /swagger-ui/index.html
  // exports.static = {
  //   dir: [{ prefix: '/swagger-ui', dir: path.join(__dirname, '../app/public') }],
  // }

  // Override the default configuration
  config.static = {
    dir: [
      { prefix: '/public2/', dir: path.join(appInfo.baseDir, 'app/public') },
      { prefix: '/swagger-ui/', dir: swaggerUIAbsolutePath },
    ],
  };
  return config;
};

Configuration

// {app_root}/config/config.default.js
exports.swagger = {
  swaggerDefinition: {
    swagger: '2.0',
    info: {
      // API informations (required)
      description: 'This is a sample server Petstore server.  You can find out more about     Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For this sample, you can use the api key `special-key` to test the authorization     filters.', // Description (optional)
      version: '1.0.0', // Version (required)
      title: 'Swagger Petstore', // Title (required)
      termsOfService: 'http://swagger.io/terms/',
      contact: {
        email: '[e-mail]',
      },
      license: {
        name: 'Apache 2.0',
        url: 'http://www.apache.org/licenses/LICENSE-2.0.html',
      },
    },
    host: 'petstore.swagger.io',
    basePath: '/v2',
    securityDefinitions: {
      petstore_auth: {
        type: 'oauth2',
        authorizationUrl: 'http://petstore.swagger.io/oauth/dialog',
        flow: 'implicit',
        scopes: {
          'write:pets': 'modify pets in your account',
          'read:pets': 'read your pets',
        },
      },
      api_key: {
        type: 'apiKey',
        name: 'api_key',
        in: 'header',
      },
    },
  },
  apis: [
    './test/fixtures/apps/swagger-jsdoc-test/app/controller/**.js',
    './test/fixtures/apps/swagger-jsdoc-test/app/swagger/schemas/**.yaml',
  ],
};

see config/config.default.js for more detail.

see https://github.com/Surnet/swagger-jsdoc for more detail.

Example

see test/swagger-jsdoc.test.js for more detail.

see test/fixtures/apps/swagger-jsdoc-test/app/controller/pet.js for more detail.

see test/fixtures/apps/swagger-jsdoc-test/app/swagger/schemas/pet.yaml for more detail.

Questions & Suggestions

Please open an issue here.

License

MIT