yanshijie-el / egg-swagger-doc Goto Github PK

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

一个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

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

If you use

/**
 * @Controller user
 */

in two different file . we have user and user[1] as tag in swagger ui

baseResponse: { data: { type: ['string', 'array', 'object'], required: true } }

比如 data 的 type，'string', 'array', 'object' 这三种类型都有可能，这样要怎么配置？

请问,如果在api的请求头需要加Authorization,要如何配置?

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

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

使用Authorize按钮登陆之后，前端发送的请求里没带对应的header

Why my operationId is like controller-myTag-undefined ?

Always we have a default : successful operation in response , It must be removed

contract目录下面的文件怎么定义 有没有示例？

Is it possible to support initOAuth ?
https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md

“应用启动后访问/swaagger-ui.html可以浏览页面”=》“/swagger-ui.html”

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?

why [@request body] default param's name is 'body'
./lib/document/index.js: 435

1. 对app/controller/user.js进行注释是能够自动配置swagger的，但是对app/controller/admin/user.js进行配置就没有效果？怎么解决？

2.请问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

想请教一下，配置这个参数securityDefinitions后，是如何在项目里面使用的呀，我对于swagger相关概念还不太熟

这样配置之后，使用中间件，ioc注入全部失效了，请问是怎么回事，swagger的页面是能出来的，但是请求接口都不对了

How can I document multipart upload?
https://swagger.io/docs/specification/describing-request-body/file-upload/

In #8 I found that tagName is incorrect

Can youn fix it?

因查找到您代码中标注暂不实现这一功能，但本地项目目录较多所以存在很多子目录方便管理，可以实现这一功能吗？

hello，项目clone下来后，跑npm run test跑不通，/swagger-ui.html和/swagger-doc都404，需要做什么操作吗

@Ysj291823 You release a latest version 18 hours ago , you release it from release branch

release...master

My PRs #60 and #61 is not included in the release branch

能不能全局使用securityDefinitions

Hello.

I have added securityDefinitions like this:

securityDefinitions: {
    Bearer: {
      type: 'apiKey',
      name: 'Authorization',
      in: 'header',
    }
  },
 enableSecurity: true

Even if I add my token value in Authorize field in Swagger doc, there are no any header arguments:

Did I miss something?

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"
         }
      }
   ]
}

`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注释去掉就可以了，，这是为什么？怎么处理？

https://github.com/Ysj291823/egg-swagger-doc/blob/418558eab209c98796ba2c9bbf4905af533c7514/lib/document/index.js#L177

在使用TypeScript时，若是使用npm start运行时，会先将.ts文件转为.js，同时会保留.ts文件，那么上面代码行引入的文件就会时.ts文件，其typscript语法是无法解析的，会报错。

我提了PR #53 来避免这个问题，如果作者有更好的解决办法，请修复。
祝好～！

用ts的话，后缀是ts，我看了下扫描里面写死了扫描后缀为.js的文件，能不能加一个配置项，默认为扫描.js，但是可以配置为扫描其他的后缀

由于项目需要，controller 具有多层目录结构

/controller
      /v1
         /user.js
      /v2
        /user.js

看源码已经扫描了多层目录，但是没有将扫描结果正确合并

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

请问是否支持全局中间件或者指定路由的中间件？

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 ?

Hi,
我看到下面将枚举enum转换为了数组array，请问这是出于什么目的？它造成了不能为空也不能设置默认值的问题，egg-validate本身是支持enum为空且设置默认值的。
https://github.com/Ysj291823/egg-swagger-doc/blob/5680d86e3a6ea95d69062c4a1679b42c81afd3f1/lib/contract/index.js#L156-L160

// 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上的校验没法继续了

@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?

如题

升级2.2.5之后会忽略@controller，扫描所有文件和方法，当其他文件中没有接口注释时会报错
egg-swagger-doc/lib/comment/index.js:14:47

@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

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

默认的UI样式不太好用，想问一下怎么自定义的

项目链接 https://github.com/taccisum/swagger-doc-snippets

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

@Ysj291823 能在README上帮我贴上去不，希望方便更多的同学们

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.