npm

egg-swagger2

1.0.4 • Public • Published

egg-swagger2

NPM version build status Test coverage David deps Known Vulnerabilities npm download

Not in the way of annotation to generate swagger doc by swagger 2.0.Fully support the swagger syntax configuration.Recommended for use in app/router.js

Install

$ npm i egg-swagger2 --save

Usage

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

Configuration

// {app_root}/config/config.default.js
exports.swagger2 = {
  enable:false, // disable swagger , default true
  base: {
    /* default config,support cover
    schemes: [
        'http',
    ],
    host: '127.0.0.1:7001',
    basePath: '/',
    consumes: [
    'application/json',
    ],
    produces: [
    'application/json',
    ],
    */
    info: {
      description: 'This is a test swagger-ui html',
      version: '1.0.0',
      title: 'TEST',
      contact: {
        email: 'caandoll@aliyun.com',
      },
      license: {
        name: 'Apache 2.0',
        url: 'http://www.apache.org/licenses/LICENSE-2.0.html',
      },
    },
    tags: [
      {
        name: 'admin',
        description: 'Admin desc',
      },
      {
        name: 'role',
        description: 'Role desc',
      },
    ],
    definitions:{
    // model definitions
    },
    securityDefinitions:{
    // security definitions
    }
  },
};

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

Example

// {app_root}/app/router.js
 module.exports = app => {
   const { router, controller, swagger } = app;
   router.post('/login', controller.test.postLogin);
   swagger.post('/login', {
       tags: [
         'admin',
       ],
       summary: 'Login a admin',
       description: '',
       parameters: [
         {
           in: 'body',
           name: 'body',
           description: 'admin\'s username & password',
           required: true,
           schema: {
             type: 'object',
             required: [ 'username', 'password' ],
             properties: {
               username: {
                 type: 'string',
                 description: 'admin\'s username',
               },
               password: {
                 type: 'string',
                 description: 'admin\'s password',
               },
             },
           },
         },
       ],
       responses: {
         200: {
           description: 'SUCCEED',
           schema: {
             type: 'object',
             properties: {
               status: {
                 type: 'string',
                 description: 'status',
               },
               data: {
                 type: 'object',
                 description: 'data',
                 properties: {
                   token: {
                     type: 'string',
                     description: 'token',
                   },
                 },
               },
             },
           },
         },
       },
     });
   router.get('/roles', controller.test.getRoles);
   swagger.get('/roles', {
     tags: [
       'role',
     ],
     summary: 'search role by page',
     description: '',
     parameters: [
       {
         in: 'query',
         name: 'name',
         description: 'role\'s name',
       },
       {
         in: 'query',
         name: 'pageIndex',
         description: 'pageIndex',
       },
       {
         in: 'query',
         name: 'pageSize',
         description: 'pageSize',
       },
     ],
     responses: {
       200: {
          description: 'SUCCEED',
          schema: {
            type: 'object',
            properties: {
              status: {
                type: 'string',
                description: 'status',
              },
              datas: {
                type: 'array',
                description: 'result datas',
                properties: {
                  token: {
                    type: 'string',
                    description: 'token',
                  },
                },
              },
              pageIndex:{
                type: 'number',
                description: 'pageIndex',
              },
              pageSize:{
                type: 'number',
                description: 'pageSize',
              },
              totalCount:{
                type: 'number',
                description: 'totalCount',
              },
            },
          },
        },
     },
   });
 };

Questions & Suggestions

Please open an issue here.

Other

License

MIT

Package Sidebar

Install

npm i egg-swagger2

Weekly Downloads

76

Version

1.0.4

License

MIT

Unpacked Size

11.5 MB

Total Files

20

Last publish

Collaborators

  • caando11