koa-swagger-decorator
koa-swagger-decorator copied to clipboard
Cody2333
Add support for $ref to model definitions
提供了 swaggerOptions， 可以在里面定义 model 示例如下
router.swagger({
title: 'APP-SERVER',
description: 'API DOC',
version: '1.0.0',
swaggerOptions: {
definitions: {
User: {
properties: {
id: { type: 'number' },
name: { type: 'string' }
},
type: 'object',
}
}
}
});
好哒，多谢，这样做确实可以实现，我现在也是使用这样的方式做的。
但是，有没有一种方式去自动的生成这些model呢，比如对request和response的结构自动实现model的定义？
我现在是在自己的项目中遍历某一个文件夹并添加其中所有的module到上面配置中，来实现的，这样总感觉有一些别扭。
同时，当我使用'tags'或者tagsAll时，发现生成的swagger文件并没有在根结构的'tags'中添加定义，只是在paths的子项中添加了，有没有自动添加tag到根结构的计划呢？
对于自动实现 model 有啥好的想法么？我对这部分了解的不多。现在这个库对于 swagger 没有提供完全的支持，只是将日常开发常用到的功能做了包装。
根节点 tag 的功能现在也只能在 swaggerOptions 添加。因为根节点的 tag 本质是是对于 tag 的描述，应该是属于初始化 swagger doc 时的操作，感觉没必要自动生成。
可以通过一个单独的文件来维护 swaggerOptions 中的内容，因为本身是一个简单的 object，具体的实现的结构由你自己定义，这个库只是简单的把这些配置加到根节点上
关于自动生成model，看到这个库生成的swagger页面是没有model或者说definition的部分，我觉得这部分是应该加进去的，然后在response或者request的使用引用$ref的方式。 至于如何自动生成，我觉得可以实现一个@model的注解器，或者指定一个文件夹(例如~/app/contract)下所有的module都自动解释为自定义model。我个人倾向于第二种方式，因为在egg-swagger-doc库里是用的这种方法。
关于自动添加tag，我的想法是当我在controller当中标记了一个不存在的tag时，可以自动生成一个根节点的tag，包括name和description。因为按照现在的功能，当我在paths中指明了一个不存在的tag时，swagger页面也能做到按这个tag去做分组。
当然，如果这个想法与你的想法有些相悖，还是由你来决定。
这是一个不错的工具库，相比较前文提到的egg-swagger-doc当中所使用的注释的方式，这里的注解器方式显然更容易避免错误。
$ref 实际上是 swagger 为了能使 model 复用提供的一个方法，但是对于 js 中的 object 天然是可以复用的，所以最初没有考虑加 $ref 的功能。
不过可以提供一个加载 model 的方法，对 model 的格式做一个 wrapper，与参数中的 schema 保持结构一致
//model.js
export const UserSchema = {
id: {type: 'string', required: true},
name: {type: 'string'}
}
// routes/user.js
import {UserSchema} from ../model.js
export class UserRouter {
@request('GET','/user',)
@query(UserSchema)
async getOne(ctx){}
}
// routes/index.js
import SwaggerRouter from 'koa-swagger-decorator'
import {UserSchema} from ../model.js
const router = new SwaggerRouter()
...
router.model(UserSchema) // 添加 model 到根节点
// router.loadModel('../model.js')
嗯，js的object可以复用没问题，但这样的话在swagger页面中复用这一逻辑就体现不出来了，这样提供出swagger作为api参考时，返回值或者请求的结构没有一个抽象提取，好像不是很方便。
提到的加载model的方法其实还是手动添加的，不论是用router.model也好，在swaggerOptions中添加definitions也好，都做不到自动添加。其实我想要的是按照一些规则自动添加，不需要我去import需要的model，然后在添加进去。
When using openapi-generator it also uses $ref name to generate TS type. Is it possible to give inline JSON a name?
When using openapi-generator it also uses $ref name to generate TS type. Is it possible to give inline JSON a name?
+1
