npmpackage.info

Gathering detailed insights and metrics for egg-swagger-doc-custom

egg-swagger-doc-custom - 2.3.3 | npmpackage.info

egg-swagger-doc-custom

swagger-ui for egg

2.3.3

194

MIT

JavaScript

8.79 MB

2.3

Installations

npm install egg-swagger-doc-custom

Developer Guide

BETA

Typescript

No

Module System

N/A

Min. Node Version

>=8.0.0

Node Version

16.16.0

NPM Version

8.11.0 Pull Requests

Open

21

Total

53

Closed

15

Merged

17

Issues

Open

43

Total

71

Closed

28

Releases

Unable to fetch releases

Languages

JavaScript

HTML

JavaScript (88.19%)

HTML (11.81%)

Developer

Ysj291823

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

GitHub Statistics

MIT License

194 Stars

120 Commits

63 Forks

6 Watchers

16 Branches

9 Contributors

Updated on May 15, 2025

Maintainers

View All 9 Contributors

Package Meta Information

Latest Version

2.3.3

Package Id

egg-swagger-doc-custom@2.3.3

Unpacked Size

8.79 MB

Size

2.21 MB

File Count

NPM Version

8.11.0

Node Version

16.16.0

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

koa-static-cache

Dev Dependencies

autod autod-egg egg egg-bin egg-ci egg-mock eslint eslint-config-egg webstorm-disable-index

egg-swagger-doc

应用于eggjs的plugin,可自动生成SwaggerUI。应用启动后访问/swaagger-ui.html可以浏览页面，访问/swagger-doc,获取swaggerjson. 这是一个简单例子，详见here

特别推荐

如下是taccisum同学开发的一个VSCode代码片段插件，能够自动生成swagger-doc的注释内容，同学们可以下载试试.

项目地址：https://github.com/taccisum/swagger-doc-snippets

因目前还没有发布到插件市场，可以通过 https://github.com/taccisum/swagger-doc-snippets/releases 手动安装。

Install

1$ npm i egg-swagger-doc --save

Usage

1// {app_root}/config/plugin.js
2exports.swaggerdoc = {
3  enable: true,
4  package: 'egg-swagger-doc',
5};

Configuration

1// {app_root}/config/config.default.js
2exports.swaggerdoc = {
3  dirScanner: './app/controller',
4  apiInfo: {
5    title: 'egg-swagger',
6    description: 'swagger-ui for egg',
7    version: '1.0.0',
8  },
9  schemes: ['http', 'https'],
10  consumes: ['application/json'],
11  produces: ['application/json'],
12  securityDefinitions: {
13    // apikey: {
14    //   type: 'apiKey',
15    //   name: 'clientkey',
16    //   in: 'header',
17    // },
18    // oauth2: {
19    //   type: 'oauth2',
20    //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
21    //   flow: 'password',
22    //   scopes: {
23    //     'write:access_token': 'write access_token',
24    //     'read:access_token': 'read access_token',
25    //   },
26    // },
27  },
28  enableSecurity: false,
29  // enableValidate: true,
30  routerMap: false,
31  enable: true,
32};

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

Introduce

完成插件引入之后，如果不修改默认配置，应用启动后，会自动扫描app/controller和app/contract下的文件。controller下的文件先不做描述。contract下的文件为定义好的请求体和响应体。

实验性功能：如果routerMap为true,允许自动生成API路由

@Controller

格式：@Controller {ControllerName}

a.如果文件第一个注释块中存在标签@Controller，应用会扫描当前文件下的所有注释块，否则扫描将会跳过该文件。
b.如果不标示ControllerName，程序会将当前文件的文件名作为ControllerName。

例：

1/**
2 * @Controller user
3 */
4class UserController extends Controller {
5  //some method
6}

@Router

格式：@Router {Mothod} {Path}

a.Mothod,请求的方法(post/get/put/delete等)，不区分大小写。
b.Path,请求的路由。

@Request

格式：@Request {Position} {Type} {Name} {Description}

a.position.参数的位置,该值可以是body/path/query/header/formData.
b.Type.参数类型，body之外位置目前只支持基础类型,integer/string/boolean/number，及基础类型构成的数组，body中则支持contract中定义的类型。如果position是formData还将支持 file 类型
c.Name.参数名称.如果参数名称以*开头则表示必要，否则非必要。
d.Description.参数描述
c.如果你想给query或者path的参数设置example，你可以在Description前添加以'eg:'开头的参数，实例如下
@Request query string contactId eg:200032234567 顾问ID

@Response

格式：@Response {HttpStatus} {Type} {Description}

a.HttpStatus.Http状态码。
b.Type.同Request中body位置的参数类型。
d.Description.响应描述。

@Deprecated

如果注释块中包含此标识，则表示该注释块注明的接口，未完成或不启用。

@Description

格式：@Description {Description}

接口具体描述

@Summary

格式：@Summary {Summary}

接口信息小标题

例：

1/**
2 * @Controller user
3 */
4class HomeController extends Controller {
5  /**
6   * @Router POST /user
7   * @Request body createUser name description-createUser
8   * @Request header string access_token
9   * @Response 200 baseResponse ok
10   */
11  async index() {
12    this.ctx.body = 'hi, ' + this.app.plugins.swagger.name;
13  }

如果在config中开启并定义了securityDefinitions,默认enableSecurity为false.则可在注释块中加入@apikey，加入安全验证。也可定义成其他名字，只需@定义好的字段名就好。关于securityDefinitions的定义可以自行搜索。

1exports.swaggerdoc = {
2  securityDefinitions: {
3    apikey: {
4      type: 'apiKey',
5      name: 'clientkey',
6      in: 'header',
7    },
8    // oauth2: {
9    //   type: 'oauth2',
10    //   tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
11    //   flow: 'password',
12    //   scopes: {
13    //     'write:access_token': 'write access_token',
14    //     'read:access_token': 'read access_token',
15    //   },
16    // },
17  },
18  enableSecurity: true,
19};

contract定义

关于Contract的定义其实在测试代码里面，已经把支持的所有情况都定义出来了。详见here,这里我简单说明一下，以下是测试代码中的部分contract。

1module.exports = {
2  createResource: {
3    resourceId: { type: 'string', required: true, example: '1' },
4    resourceNametrue: { type: 'string', required: true },
5    resourceType: { type: 'string', required: true, enum: ['video', 'game', 'image'] },
6    resourceTag: { type: 'array', itemType: 'string' },
7    owner: { type: 'User', required: true },
8    owners: { type: 'array', itemType: 'User' }
9  },
10};

@基础类型

1module.exports = {
2  Model名称:{
3    字段名称: { type: 字段类型，required: 字段必要性, example: 示例}
4  }
5}

注：type可以是array之外的类型，包括自定义的类型，目前自定义类型不支持example

@ENUM

1module.exports = {
2  Model名称:{
3    字段名称: { type: 字段类型，required: 字段必要性, enum:[]}
4  }
5}

注: type只能是string或number，enum为具体的数值组成的集合

@ARRAY

1module.exports = {
2  Model名称:{
3    字段名称: { type: "array"，required: 字段必要性, itemType:数组元素类型}
4  }
5}

type为array,itemType为具体的数组元素类型，支持自定义类型。

@自定义类型

关于自定义类型，必须定义在contract目录下，在contract下的其他类型中使用时，直接使用Model名称引入。

因为contract的定义和validate-rule的定义具有极大的相似性，所以目前的版本中定义contract的同时会简单的生成相应的validate-rule.具体的使用'ctx.rule.'加Model名称直接引入。

上面的model，在做验证的时候就可以使用如下的方式(需使用egg-validate)

1
2ctx.validate(ctx.rule.createResource, ctx.request.body);
3

Questions & Suggestions

Please open an issue here.

License

MIT

No vulnerabilities found.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

4

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

Fuzzing

Determines if the project uses fuzzing.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Reason

82 existing vulnerabilities detected

Details

Warn: Project is vulnerable to: GHSA-6chw-6frg-f759
Warn: Project is vulnerable to: GHSA-v88g-cgmw-v5xw
Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw
Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
Warn: Project is vulnerable to: GHSA-c6rq-rjc2-86v2
Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
Warn: Project is vulnerable to: GHSA-h452-7996-h45h
Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
Warn: Project is vulnerable to: GHSA-w573-4hg7-7wgq
Warn: Project is vulnerable to: GHSA-9j49-mfvp-vmhm
Warn: Project is vulnerable to: GHSA-wm7h-9275-46v2
Warn: Project is vulnerable to: GHSA-4gmj-3p3h-gm8h
Warn: Project is vulnerable to: GHSA-qrmc-fj45-qfc2
Warn: Project is vulnerable to: GHSA-gjm5-83cw-p3p2
Warn: Project is vulnerable to: GHSA-8r6j-v8pm-fqw3
Warn: Project is vulnerable to: MAL-2023-462
Warn: Project is vulnerable to: GHSA-q42p-pg8m-cqh6
Warn: Project is vulnerable to: GHSA-w457-6q6x-cgp9
Warn: Project is vulnerable to: GHSA-62gr-4qp9-h98f
Warn: Project is vulnerable to: GHSA-f52g-6jhx-586p
Warn: Project is vulnerable to: GHSA-2cf5-4w76-r9qv
Warn: Project is vulnerable to: GHSA-3cqr-58rm-57f8
Warn: Project is vulnerable to: GHSA-g9r4-xpmj-mj65
Warn: Project is vulnerable to: GHSA-q2c6-c6pm-g3gh
Warn: Project is vulnerable to: GHSA-765h-qjxv-5f44
Warn: Project is vulnerable to: GHSA-f2jv-r9rf-7988
Warn: Project is vulnerable to: GHSA-43f8-2h32-f4cj
Warn: Project is vulnerable to: GHSA-pc5p-h8pf-mvwp
Warn: Project is vulnerable to: GHSA-qqgx-2p2h-9c37
Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
Warn: Project is vulnerable to: GHSA-2pr6-76vf-7546
Warn: Project is vulnerable to: GHSA-8j8c-7jfh-h6hx
Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h
Warn: Project is vulnerable to: GHSA-6c8f-qphg-qjgp
Warn: Project is vulnerable to: GHSA-593f-38f6-jp5m
Warn: Project is vulnerable to: GHSA-x2rg-q646-7m2v
Warn: Project is vulnerable to: GHSA-4xc9-xhrj-v574
Warn: Project is vulnerable to: GHSA-x5rq-j2xg-h7qm
Warn: Project is vulnerable to: GHSA-jf85-cpcp-j695
Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9
Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm
Warn: Project is vulnerable to: GHSA-4xcv-9jjx-gfj3
Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
Warn: Project is vulnerable to: GHSA-f8q6-p94x-37v3
Warn: Project is vulnerable to: GHSA-vh95-rmgr-6w4m
Warn: Project is vulnerable to: GHSA-xvch-5gv4-984h
Warn: Project is vulnerable to: GHSA-fhjf-83wg-r2j9
Warn: Project is vulnerable to: GHSA-8hfj-j24r-96c4
Warn: Project is vulnerable to: GHSA-wc69-rhjr-hc9g
Warn: Project is vulnerable to: GHSA-56x4-j7p9-fcf9
Warn: Project is vulnerable to: GHSA-v78c-4p63-2j6c
Warn: Project is vulnerable to: GHSA-4c7m-wxvm-r7gc
Warn: Project is vulnerable to: GHSA-pch5-whg9-qr2r
Warn: Project is vulnerable to: GHSA-x77j-w7wf-fjmw
Warn: Project is vulnerable to: GHSA-hj48-42vr-x3v9
Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
Warn: Project is vulnerable to: GHSA-hrpp-h998-j3pp
Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
Warn: Project is vulnerable to: GHSA-4g88-fppr-53pp
Warn: Project is vulnerable to: GHSA-4jqc-8m5r-9rpr
Warn: Project is vulnerable to: GHSA-j44m-qm6p-hp7m
Warn: Project is vulnerable to: GHSA-3jfq-g458-7qm9
Warn: Project is vulnerable to: GHSA-r628-mhmh-qjhw
Warn: Project is vulnerable to: GHSA-9r2w-394v-53qc
Warn: Project is vulnerable to: GHSA-5955-9wpr-37jh
Warn: Project is vulnerable to: GHSA-qq89-hq3f-393p
Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36
Warn: Project is vulnerable to: GHSA-29xr-v42j-r956
Warn: Project is vulnerable to: GHSA-3329-pjwv-fjpg
Warn: Project is vulnerable to: GHSA-p6j9-7xhc-rhwp
Warn: Project is vulnerable to: GHSA-89gv-h8wf-cg8r
Warn: Project is vulnerable to: GHSA-gcv8-gh4r-25x6
Warn: Project is vulnerable to: GHSA-gmv4-r438-p67f
Warn: Project is vulnerable to: GHSA-8h2f-7jc4-7m3m
Warn: Project is vulnerable to: GHSA-3vjf-82ff-p4r3
Warn: Project is vulnerable to: GHSA-g694-m8vq-gv9h
Warn: Project is vulnerable to: GHSA-c4w7-xm78-47vh
Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp

Score

2.3

/10

Last Scanned on 2025-07-14

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More