Gathering detailed insights and metrics for egg-swagger-doc
Gathering detailed insights and metrics for egg-swagger-doc
Installations
npm install egg-swagger-docDeveloper Guide
BETA
Typescript
No
Module System
N/A
Min. Node Version
>=8.0.0
Node Version
8.11.1
NPM Version
6.4.1
Releases
Unable to fetch releases
Languages
2
JavaScript
HTML
JavaScript (88.19%)
HTML (11.81%)
Developer
Ysj291823
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
194 Stars
120 Commits
63 Forks
6 Watchers
16 Branches
9 Contributors
Updated on May 15, 2025
Maintainers
1
Package Meta Information
Latest Version
2.3.2
Package Id
egg-swagger-doc@2.3.2
Unpacked Size
8.79 MB
Size
2.23 MB
File Count
26
NPM Version
6.4.1
Node Version
8.11.1
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
egg-swagger-doc
应用于eggjs的plugin,可自动生成SwaggerUI。应用启动后访问/swaagger-ui.html可以浏览页面，访问/swagger-doc,获取swaggerjson. 这是一个简单例子，详见here
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
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
Found 8/18 approved changesets -- score normalized to 4
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 20 are checked with a SAST tool
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