Neurologically Paralyzing Mouseovers

    swagger-egg

    1.7.5 • Public • Published

    swagger-egg

    swagger-egg

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

    中文文档

    An egg-swagger plugin (support Typescript) for serving a Swagger UI, params should follow JSON Schema specification (recommend use Ajv),using Swagger (OpenAPI v2) schemas automatically generated from your controller JSDoc comments.

    CAUTION: Require Node.js 10.x or higher!

    Install

    $ npm i swagger-egg --save

    Usage

    Enable this plugin, visting index.html under static resource directory and you will get the Swagger UI page. Visiting http://localhost:7001/public/index.html to get the default Swagger-UI page. Project Example:

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

    Configuration

    • swagger.info is optional and will be generated from your application's package.json if not exist.
    • swagger.tags is required if controller's JSDoc comments used tags.
    // {app_root}/config/config.default.js
    exports.swaggerEgg = {
      schema: {
        path: '/app/schema', // JSON Schema directory
      },
      swagger: {
        info: {
          title: 'Test swagger',
          description: 'Testing the Fastify swagger API',
          version: '0.1.0'
        },
        externalDocs: {
          url: 'https://swagger.io',
          description: 'Find more info here'
        },
        host: '127.0.0.1:7001', // should be egg server's host, otherwise result in cross origin error
        schemes: ['http', 'https'],
        consumes: ['application/json'],
        produces: ['application/json'],
        tags: [
          { name: 'user', description: 'User related end-points' }
        ],
        securityDefinitions: {
          api_key: {
            type: 'apiKey', // basic/apiKey/oauth2
            name: 'Authorization', // selfdefined parameter, usually use 'Authorization'
            in: 'header', // query or header, usually use 'header'
          },
          github_auth: {
            type: 'oauth2',
            authorizationUrl: 'http://swagger.io/api/oauth/dialog',
            flow: 'implicit',
            scopes: {
              'write:homes': 'modify home info',
              'read:homes': 'read home info',
            },
          },
        },
        security: [
          {
            api_key: [], // select 'api_key' to security(defined in `securityDefinitions`)
          },
        ], // Cacution: security is array type
        typescriptJsonSchema: false, // use typescript json schema. (see: https://github.com/YousefED/typescript-json-schema)
      }
    };

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

    Grammer

    #swagger-api

    #swagger-api in front of JSDoc comments is required!

      /**
       * #swagger-api
       *
       * @function index
       */
      async index() {
        this.ctx.body = 'hi, #swagger-api example'
      }

    @function {Name}

    The JSDoc @function is required, which is used to search router info from app/router.js.

      /**
       * Function example #swagger-api
       *
       * @function index
       */
      async index() {
        this.ctx.body = 'hi, function example'
      }

    @summary {functionSummary}

    The JSDoc @summary is used to describe the function's summary.

      /**
       * Function example #swagger-api
       *
       * @function index
       * @summary This is function's summary.
       */
      async index() {
        this.ctx.body = 'hi, summary example'
      }

    @description #tags {Tag1} {Tag2} ...

    #tags is used for logical grouping of operations by resources or any other qualifier.

    NOTE: Multiple tags should be separated by whitespace.

      /**
       * Tags example #swagger-api
       *
       * @function index
       * @description #tags user admin
       */
      async index() {
        this.ctx.body = 'hi, tags example'
      }

    @description #produces {Mimetype1} {Mimetype2} ...

    #produces is used for declaring API response mimetype.

    NOTE: Multiple mimetypes should be separated by whitespace.

      /**
       * Produces example #swagger-api
       *
       * @function index
       * @description #produces application/json
       */
      async index() {
        this.ctx.body = 'hi, produces example'
      }

    @description #consumes {Mimetype1} {Mimetype1} ...

    #consumes is used for declaring API request mimetype.

    NOTE: Multiple mimetypes should be separated by whitespace.

      /**
       * Consumes example #swagger-api
       *
       * @function index
       * @description #consumes application/json
       */
      async index() {
        this.ctx.body = 'hi, consumes example'
      }

    @description #parameters {PrameterName} {In} {ParameterSchema|Type} {Required} - {Description}

    #parameters is used for declaring api request parameters.

    NOTE: Description is separated by - and others are separated by whitespace.

    NOTE:

    • In should be within 'query', 'header', 'path', 'formData', 'body' according to Swagger specification.
    • Required should be boolean type.
    • Type should be within 'string', 'number', 'integer', 'boolean', 'array', 'file'.
      /**
       * Parameters example #swagger-api
       *
       * @function index
       * @description #parameters id path schema.id true - id parameter
       */
      async index() {
        this.ctx.body = 'hi, parameters example'
      }

    @description #responses {HttpStatus} {ResponseSchema} - {Description}

    #responses is used for declaring api response info.

    NOTE: Description is separated by - and others are separated by whitespace.

      /**
       * Responses example #swagger-api
       *
       * @function index
       * @description #responses schema.user - user responses
       */
      async index() {
        this.ctx.body = 'hi, responses example'
      }

    Schema Example

    Schema should follow the JSON Schema specification. You can use Ajv to validate it.

    Change swaggerEgg.schema.path field in config file if you want to redefine it.

    // {app_root}/app/schema/users.js
    
    module.exports = {
      type: 'object',
      properties: {
        id: {
          type: 'string',
          description: 'user id'
        },
        name: {
          type: 'string',
          description: 'user name'
        },
        age: {
          type: 'number',
          description: 'user age'
        },
      },
      required: [ 'id', 'name', 'age' ],
      additionalProperties: false,
    };

    Controller Example

    // {app_root}/app/controller/users.js
    
    const Controller = require('egg').Controller;
    
    class UserController extends Controller {
    
      /**
       * Index action #swagger-api
       *
       * @function index
       * @memberof UserController
       * @description #tags user
       * @description #produces application/json
       * @description #parameters index query schema.definitions.index true - parameter index
       * @description #responses 200 schema.user - index response
       */
      async index() {
        this.ctx.body = 'hi, index action' + this.app.plugins.swaggerEgg.name;
      }
    
      /**
       * New action #swagger-api
       *
       * @function new
       * @memberof UserController
       * @description #tags user
       * @description #consumes application/x-www-form-urlencoded
       * @description #produces application/json
       * @description #parameters userInfo body schema.user true - parameter userInfo
       * @description #responses 200 schema.user - new response
       */
      async new() {
        this.ctx.body = 'hi, new action' + this.app.plugins.swaggerEgg.name;
      }
    
      /**
       * Show action #swagger-api
       *
       * @function show
       * @memberof UserController
       * @description #tags user
       * @description #produces application/json
       * @description #parameters id path schema.definitions.id true - parameter id
       * @description #responses 200 schema.user - show response
       */
      async show() {
        this.ctx.body = 'hi, show action' + this.app.plugins.swaggerEgg.name;
      }
    
      /**
       * Edit action #swagger-api
       *
       * @function edit
       * @memberof UserController
       * @description #tags user
       * @description #consumes application/x-www-form-urlencoded
       * @description #produces application/json
       * @description #parameters id path schema.definitions.id true - parameter id
       * @description #parameters userInfo body schema.user true - parameter userInfo
       * @description #responses 200 schema.user - edit response
       */
      async edit() {
        this.ctx.body = 'hi, edit action ' + this.app.plugins.swaggerEgg.name;
      }
    
      /**
       * Create action #swagger-api
       *
       * @function create
       * @memberof UserController
       * @description #tags user
       * @description #consumes application/x-www-form-urlencoded
       * @description #produces application/json
       * @description #parameters userInfo body schema.user true - parameter userInfo
       * @description #responses 200 schema.user - create response
       */
      async create() {
        this.ctx.body = 'hi, create action ' + this.app.plugins.swaggerEgg.name;
      }
    
      /**
       * Update action #swagger-api
       *
       * @function update
       * @memberof UserController
       * @description #tags user
       * @description #consumes application/x-www-form-urlencoded
       * @description #produces application/json
       * @description #parameters id path schema.definitions.id true - parameter id
       * @description #parameters userInfo body schema.user true - parameter userInfo
       * @description #responses 200 schema.user - update response
       */
      async update() {
        this.ctx.body = 'hi, update action ' + this.app.plugins.swaggerEgg.name;
      }
    
      /**
       * Destory action #swagger-api
       *
       * @function destory
       * @memberof UserController
       * @description #tags user
       * @description #consumes application/json
       * @description #produces application/json
       * @description #parameters id path schema.definitions.id false - parameter id
       * @description #responses 200 schema.user - destory response
       */
      async destory() {
        this.ctx.body = 'hi, destory action ' + this.app.plugins.swaggerEgg.name;
      }
    }
    
    module.exports = UserController;

    Questions & Suggestions

    Please open an issue here.

    License

    MIT

    Install

    npm i swagger-egg

    DownloadsWeekly Downloads

    2

    Version

    1.7.5

    License

    MIT

    Unpacked Size

    65.6 kB

    Total Files

    15

    Last publish

    Collaborators

    • jsonma