All Projects → JsonMa → swagger-egg

JsonMa / swagger-egg

Licence: MIT license
Eggjs Swagger-UI API文档自动生成插件(如果喜欢请点赞支持)。Egg swagger documentation generator(welcome to star this project).

Programming Languages

javascript
184084 projects - #8 most used programming language
typescript
32286 projects

Projects that are alternatives of or similar to swagger-egg

grlc
grlc builds Web APIs using shared SPARQL queries
Stars: ✭ 118 (+280.65%)
Mutual labels:  swagger-ui
IGeekFan.AspNetCore.Knife4jUI
support .NET Core3.0+,.NET Standard2.0 Swagger UI knife4j ui,you can use NSwagger or Swashbuckle.AspNetCore in packages
Stars: ✭ 178 (+474.19%)
Mutual labels:  swagger-ui
jsdoc-syntax.vim
Standalone JSDoc syntax for vim
Stars: ✭ 17 (-45.16%)
Mutual labels:  jsdoc
jekyll-swagger-ui
A Jekyll plugin to integrate Swagger UI into Jekyll site
Stars: ✭ 16 (-48.39%)
Mutual labels:  swagger-ui
kanban-board
Single-click full-stack application (Postgres, Spring Boot & Angular) using Docker Compose
Stars: ✭ 138 (+345.16%)
Mutual labels:  swagger-ui
Ktor-OpenAPI-Generator
Ktor OpenAPI/Swagger 3 Generator
Stars: ✭ 203 (+554.84%)
Mutual labels:  swagger-ui
examplejs
A tool for converting example code into test cases
Stars: ✭ 44 (+41.94%)
Mutual labels:  jsdoc
jsdoc-api
A programmatic interface for jsdoc3 with a few extra features
Stars: ✭ 55 (+77.42%)
Mutual labels:  jsdoc
spring-boot-starter-swagger
Spring Boot Swagger UI Starter
Stars: ✭ 14 (-54.84%)
Mutual labels:  swagger-ui
net-api
A documented REST API which returns structured data from network devices
Stars: ✭ 73 (+135.48%)
Mutual labels:  swagger-ui
jsdoc-action
📖 GitHub Action to build JSDoc documentation
Stars: ✭ 61 (+96.77%)
Mutual labels:  jsdoc
cakephp-swagger-bake
Automatically generate OpenAPI, Swagger, and Redoc documentation from your existing CakePHP code.
Stars: ✭ 48 (+54.84%)
Mutual labels:  swagger-ui
platform
Apinf - Open source API management platform with multi proxy and protocol support
Stars: ✭ 69 (+122.58%)
Mutual labels:  swagger-ui
example-postgresql
A complete example of a "CRUD" service (UserService) built with Oat++ and using oatpp ORM with PostgreSQL.
Stars: ✭ 24 (-22.58%)
Mutual labels:  swagger-ui
django-swagger-ui
Django swagger UI is a viewer for Swagger YAML files as html.
Stars: ✭ 24 (-22.58%)
Mutual labels:  swagger-ui
openapi-viewer
Browse and test a REST API described with the OpenAPI 3.0 Specification
Stars: ✭ 85 (+174.19%)
Mutual labels:  swagger-ui
cakephp-swagger
Swagger plugin for documenting your CakePHP APIs
Stars: ✭ 61 (+96.77%)
Mutual labels:  swagger-ui
goscription
Goscription is skeleton project with simple design & clean code with Go
Stars: ✭ 36 (+16.13%)
Mutual labels:  swagger-ui
faas-swagger
Swagger for Openfaas
Stars: ✭ 19 (-38.71%)
Mutual labels:  swagger-ui
koa2-swagger-ui
Swagger UI as Koa v2 middleware
Stars: ✭ 95 (+206.45%)
Mutual labels:  swagger-ui

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

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].