yanshijie-el / egg-swagger-doc Goto Github PK
View Code? Open in Web Editor NEWswagger-ui for egg
License: MIT License
swagger-ui for egg
License: MIT License
2.请问contract文件夹需要做什么配置吗?
@Ysj291823 @mkc-yanshijie Accodring to https://swagger.io/docs/specification/2-0/describing-parameters/
Query parameters only support primitive types. You can have an array, but the items must be a primitive value type. Objects are not supported.
How can I define array query parameter?
How can I document multipart upload?
https://swagger.io/docs/specification/describing-request-body/file-upload/
We can configure consumes
and produces
like following
exports.swaggerdoc = {
dirScanner: './app/controller',
apiInfo: {
title: 'egg-swagger',
description: 'swagger-ui for egg',
version: '1.0.0',
},
schemes: ['http', 'https'],
consumes: ['application/json'],
produces: ['application/json'],
enable: true,
};
But how can set produces
of a specific method?
Assume we have a download method that produces
the application/octect-stream
能不能全局使用securityDefinitions
Please implement description
for Parameters
paths:
/users/{userId}:
get:
summary: Get a user by ID
parameters:
- in: path
name: userId
schema:
type: integer
required: true
description: Numeric ID of the user to get
After my PR #27 , unfortunately you don't release a version and I see that you have huge changes and some releases
But I see that it is not currently stable and usable
When I can have a stable version?
hello,项目clone下来后,跑npm run test
跑不通,/swagger-ui.html
和/swagger-doc
都404,需要做什么操作吗
In #8 I found that tagName
is incorrect
Can youn fix it?
why [@request body] default param's name is 'body'
./lib/document/index.js: 435
I have a fixed error schema
{
"code" : "string",
"message" : "string"
}
Can I use egg-swagger-doc
to produce the following responses in my document
{
"code" : "NOT_FOUND",
"message" : "string"
}
{
"code" : "FORBIDDEN",
"message" : "string"
}
{
"code" : "RATE_LIMIT",
"message" : "string"
}
I want to list error codes in responses
Because the definition of contract and the definition of validate-rule have great similarity, the definition of contract in the current version will simply generate the corresponding validate-rule. The specific use of 'ctx.rule.' plus the Model name directly introduced .
The above model, you can use the following method when doing verification (use egg-validate)
ctx.validate(ctx.rule.createResource, ctx.request.body);
I understand that currently it is not ready for production for instance , see https://github.com/node-modules/parameter#string
When I set format
as a regex value , it loose test
method , As you do JSON.parse(JSON.stringify(contract));
https://github.com/Ysj291823/egg-swagger-doc/blob/master/lib/swagger_rule.js#L5
Why you do this?
@Ysj291823 @mkc-yanshijie As you now the format of @Request
is
@Request {Position} {Type} {Name} {Description}
How we can have an example
for a query
field ?
因查找到您代码中标注暂不实现这一功能,但本地项目目录较多所以存在很多子目录方便管理,可以实现这一功能吗?
如题
项目链接 https://github.com/taccisum/swagger-doc-snippets
目前还没有发布到插件市场,可以通过https://github.com/taccisum/swagger-doc-snippets/releases 下载插件包手动安装
@Ysj291823 能在README上帮我贴上去不,希望方便更多的同学们
想请教一下,配置这个参数securityDefinitions后,是如何在项目里面使用的呀,我对于swagger相关概念还不太熟
baseResponse: { data: { type: ['string', 'array', 'object'], required: true } }
比如 data
的 type
,'string', 'array', 'object' 这三种类型都有可能,这样要怎么配置?
默认的UI样式不太好用,想问一下怎么自定义的
@Ysj291823 , @mkc-yanshijie If you create a controller under app/controller/foo/bar/foobar.js
then current tag name is bar
, I think it must be foo
or at least foo/bar
请问,如果在api的请求头需要加Authorization,要如何配置?
contract目录下面的文件怎么定义 有没有示例?
2019-08-16 16:20:25,122 ERROR 15776 [-/127.0.0.1/-/0ms GET /] nodejs.Error: [egg-swagger-doc] error at post:/agent/checkUser ,the type of response parameter does not exit
at generateResponse (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:370:17)
at getTag_Path (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:139:35)
at buildDocument (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:50:14)
at documentInit (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:497:7)
at module.exports.swaggerInit.app (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\index.js:10:3)
at app.beforeStart (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\app.js:8:5)
at Object.callFn (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-core\lib\utils\index.js:44:42)
at process.nextTick (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-core\lib\lifecycle.js:262:13)
at process._tickCallback (internal/process/next_tick.js:61:11)
at Function.Module.runMain (internal/modules/cjs/loader.js:745:11)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:743:3)
pid: 15776
hostname: USER-20190118FU
2019-08-16 16:20:25,124 ERROR 15776 nodejs.Error: [egg-swagger-doc] error at post:/agent/checkUser ,the type of response parameter does not exit
at generateResponse (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:370:17)
at getTag_Path (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:139:35)
at buildDocument (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:50:14)
at documentInit (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\document\index.js:497:7)
at module.exports.swaggerInit.app (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\lib\index.js:10:3)
at app.beforeStart (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-swagger-doc\app.js:8:5)
at Object.callFn (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-core\lib\utils\index.js:44:42)
at process.nextTick (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-core\lib\lifecycle.js:262:13)
at process._tickCallback (internal/process/next_tick.js:61:11)
at Function.Module.runMain (internal/modules/cjs/loader.js:745:11)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:743:3)
pid: 15776
hostname: USER-20190118FU
2019-08-16 16:20:25,124 ERROR 15776 [app_worker] start error, exiting with code:1
[2019-08-16 16:20:25.130] [cfork:master:3236] worker:15776 disconnect (exitedAfterDisconnect: false, state: disconnected, isDead: false, worker.disableRefork: true)
2019-08-16 16:20:25,131 ERROR 12376 nodejs.unhandledExceptionError: read ECONNRESET
at TCP.onStreamRead (internal/stream_base_commons.js:111:27)
errno: "ECONNRESET"
code: "ECONNRESET"
syscall: "read"
name: "unhandledExceptionError"
pid: 12376
hostname: USER-20190118FU
[2019-08-16 16:20:25.131] [cfork:master:3236] don't fork, because worker:15776 will be kill soon
2019-08-16 16:20:25,134 INFO 3236 [master] app_worker#21:15776 disconnect, suicide: false, state: disconnected, current workers: ["21"]
[2019-08-16 16:20:25.143] [cfork:master:3236] worker:15776 exit (code: 1, exitedAfterDisconnect: false, state: dead, isDead: true, isExpected: false, worker.disableRefork: true)
2019-08-16 16:20:25,144 ERROR 3236 nodejs.AppWorkerDiedError: [master] app_worker#21:15776 died (code: 1, signal: null, suicide: false, state: dead), current workers: []
at Master.onAppExit (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-cluster\lib\master.js:510:21)
at Master.emit (events.js:182:13)
at Messenger.sendToMaster (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-cluster\lib\utils\messenger.js:137:17)
at Messenger.send (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-cluster\lib\utils\messenger.js:102:12)
at EventEmitter.cluster.on (C:\Users\Administrator\Desktop\5555\htetypescript\node_modules\egg-cluster\lib\master.js:353:22)
at EventEmitter.emit (events.js:187:15)
at ChildProcess.worker.process.once (internal/cluster/master.js:193:13)
at Object.onceWrapper (events.js:273:13)
at ChildProcess.emit (events.js:182:13)
at Process.ChildProcess._handle.onexit (internal/child_process.js:240:12)
name: "AppWorkerDiedError"
pid: 3236
hostname: USER-20190118FU
@Ysj291823 You release a latest version 18 hours ago , you release it from release branch
一个api的response就是一个array,
在model中有
// 测试题
test: {
id: { type: 'integer', description: '测试题id' },
dailyReadTitle: { type: 'string', description: '测试题所在今日阅读的标题' },
planId: { type: 'integer', description: '测试题所在计划的id' },
topicId: { type: 'integer', description: '测试题所在话题的id' },
questionCode: { type: 'string', description: '测试题选项标志符' },
status: { type: 'integer', description: '测试题状态,0未答,1已答' },
questions: {
type: 'array',
itemType: 'option',
description: '测试题的问题选项',
},
},
这个请求的response是 test的array 应该如何设置 @response和 contract
使用Authorize按钮登陆之后,前端发送的请求里没带对应的header
在使用TypeScript时,若是使用npm start
运行时,会先将.ts
文件转为.js
,同时会保留.ts
文件,那么上面代码行引入的文件就会时.ts
文件,其typscript
语法是无法解析的,会报错。
我提了PR #53 来避免这个问题,如果作者有更好的解决办法,请修复。
祝好~!
由于项目需要,controller 具有多层目录结构
/controller
/v1
/user.js
/v2
/user.js
看源码已经扫描了多层目录,但是没有将扫描结果正确合并
Why my operationId is like controller-myTag-undefined
?
// app.js
app.validator.addRule('ISOTime', (rule, value) => {
if (!moment(value, moment.ISO_8601).isValid()) {
return 'time must be UTC ISO8601 format';
}
});
定义了类型之后设置为定义的类型后从ctx.rule.rule
里取到的type变成了object
,validate上的校验没法继续了
After upgrading from 1.4.3 to 1.4.3 , /swagger-ui.html
returns 404 but swagger-doc
works
I think #21 is wrong
In config we can define scopes
exports.swaggerdoc = {
...
securityDefinitions: {
oauth2: {
type: 'oauth2',
tokenUrl: 'http://petstore.swagger.io/oauth/dialog',
flow: 'password',
scopes: {
'write:access_token': 'write access_token',
'read:access_token': 'read access_token',
},
},
},
...
};
But , I think there is no option to document , what scope needed to access a method , so @scope
is needed
Hi,
我看到下面将枚举enum
转换为了数组array
,请问这是出于什么目的?它造成了不能为空也不能设置默认值的问题,egg-validate
本身是支持enum
为空且设置默认值的。
https://github.com/Ysj291823/egg-swagger-doc/blob/5680d86e3a6ea95d69062c4a1679b42c81afd3f1/lib/contract/index.js#L156-L160
升级2.2.5之后会忽略@controller,扫描所有文件和方法,当其他文件中没有接口注释时会报错
egg-swagger-doc/lib/comment/index.js:14:47
the global config is following:
config.swaggerdoc = {
parameters: [
{
description: 'user token',
name: 'accessToken',
in: 'header',
},
],
securityDefinitions: {
apiKey: {
type: 'apiKey',
description: 'user token',
name: 'accessToken',
in: 'header',
},
},
};
the two config both are not effective, i want to set a global header params
i think it will be a useful functions.
Is it possible to support initOAuth ?
https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md
If you use
/**
* @Controller user
*/
in two different file . we have user and user[1] as tag in swagger ui
Can you please implement Multiple examples for a parameter:
parameters:
- in: query
name: limit
schema:
type: integer
maximum: 50
examples: # Multiple examples
zero: # Distinct name
value: 0 # Example value
summary: A sample limit value # Optional description
max: # Distinct name
value: 50 # Example value
summary: A sample limit value # Optional description
请问是否支持全局中间件或者指定路由的中间件?
What is the usage of swaggerdoc.enable config?
https://github.com/Ysj291823/egg-swagger-doc/blob/master/config/config.default.js#L46
I think you forgot to implement it as there is no code usage and no affect when I set it as false
`class AccountController extends Controller {
/**
* @router POST /login
* @response 0 body test
* @summary 登录接口
*/
async login() {
const { ctx, app, config } = this;
const name = ctx.request.body.name;
const password = ctx.request.body.password;
const user = await app.mysql.get('user', {
name,
});
if (!user || ctx.helper.md5(password) !== user.password) {
ctx.body = ctx.ResultUtil.error(config.werror.ERR_ACCOUNT_LOGIN);
return;
}
const userJSON = JSON.stringify(user);
const token = app.jwt.sign(userJSON, app.config.jwt.secret);
ctx.body = ctx.ResultUtil.success({ user, token });
}
}`
错误信息如下:
nodejs.Error: [egg-swagger-doc] error at post:/login ,the type of response parameter does not exit
at module.exports.app (E:\node\op-new\op-new-admin\node_modules\egg-swagger-doc\lib\swagger_loader.js:122:23)
at app.beforeStart (E:\node\op-new\op-new-admin\node_modules\egg-swagger-doc\app.js:11:21)
at Object.callFn (E:\node\op-new\op-new-admin\node_modules\egg-core\lib\utils\index.js:36:42)
at process.nextTick (E:\node\op-new\op-new-admin\node_modules\egg-core\lib\egg.js:226:13)
at _combinedTickCallback (internal/process/next_tick.js:131:7)
at process._tickCallback (internal/process/next_tick.js:180:9)
at Function.Module.runMain (module.js:695:11)
at startup (bootstrap_node.js:191:16)
at bootstrap_node.js:612:3
把@response注释去掉就可以了,,这是为什么?怎么处理?
“应用启动后访问/swaagger-ui.html可以浏览页面”=》“/swagger-ui.html”
I validate my swagger doc , I have the following error
{
"messages":[
"attribute paths.'/messages/{id}'(get).[id].example is unexpected"
],
"schemaValidationMessages":[
{
"level":"error",
"domain":"validation",
"keyword":"pattern",
"message":"ECMA 262 regex \"^[^{}/ :\\\\]+(?::\\d+)?$\" does not match input string \"\"",
"schema":{
"loadingURI":"#",
"pointer":"/properties/host"
},
"instance":{
"pointer":"/host"
}
}
]
}
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.