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

@qc2168/swagger-egg

v1.7.6

Published

swagger document generator for egg.

Downloads

5

Readme

swagger-egg

swagger-egg

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

英文文档

Eggjs Swagger UI API文档自动生成插件(支持Typescript),请求及响应参数需通过JSON Schema(推荐使用Ajv)定义,并遵循 Swagger (OpenAPI v2) 规范,swagger.json 由插件通过Controller中的 JSDoc 注释自动生成。

注意: Node.js版本需要>=10.x!

插件安装

$ npm i swagger-egg --save

插件使用

Swagger-UI 以 egg-static 静态资源的形式进行访问,若static.prefix为默认值,则只需要打开http://localhost:7001/public/index.html即可获取到 Swagger-UI 页面。关于插件在项目中的使用,请参考下面的示例:

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

插件配置

  • swagger.info 是可选的,若不存在,则插件将会依据根目录下的package.json信息自动生成。
  • swagger.tags 是必选的,如果在JSDoc注释中使用了#tags标签。
  • 更多Swagger配置请参考OpenAPI V2
// {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', // 应当与egg server host保持一致,否则会有跨域的问题
    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', // 自定义的鉴权参数,通常为'Authorization'
        in: 'header', // 鉴权参数放置的位置,query 或者 header
      },
      swagger_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: [], // 鉴权方式(securityDefinitions中定义的内容)
      },
    ], // 注意: security为数组类型
  },
};

访问 config/config.default.js 查看更多默认配置。

插件语法

#swagger-api

JSDoc注释中的#swagger-api标签是必须的,插件将以该标签为标识进行注释的自动扫描。

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

@function {Name}

JSDoc注释的 @function 标签也是必须的,插件通过函数名去 app/router.js中进行扫描,以获取API的Http Method、Http Url信息。

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

@summary {functionSummary}

JSDoc @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} ...

JSDoc @description内容中的#tags标签用于声明该API用到的Swagger tag。

注意: 多个Swagger tags 间应当使用空格进行分隔。

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

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

JSDoc @description内容中的#produces 用于声明API Response MIMEtype.

注意: 多个MIMEtype使用空格进行分隔。

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

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

JSDoc @description内容中的#consumes用于声明API Request MIMEtype.

注意: 多个MIMEtype使用空格进行分隔。

  /**
   * 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}

JSDoc @description内容中的#parameters用于声明API Request Parameters.

注意: description需单独使用-分隔开(遵循JSDoc写法)其它参数使用空格进行分隔。

注意:

  • 按照Swagger规范,变量In的取值范围只能为'query', 'header', 'path', 'formData', 'body'
  • 变量Required的值只能为true或者false
  • 变量Type的取值范围只能为['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}

JSDoc @description内容中的#responses 用于声明API Response。

注意: description需单独使用-分隔开(遵循JSDoc写法)其它参数使用空格进行分隔。

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

Schema Example

Schema的写法需遵循 JSON Schema 规范,推荐使用Ajv 进行参数校验。

更改 swaggerEgg.schema.path 字段可制定待扫描的Schema文件路径。

// {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 示例

// {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;

问题及建议

请创建 issue 来反馈您的问题及建议。同时欢迎更多的小伙伴能奉献一款swagger-egg vscode插件,供大家使用。

License

MIT