npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

swagger-egg

v1.7.6

Published

swagger document generator for egg.

Downloads

275

Readme

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