opss 提供基于 typescript 推断的全自动文档生成能力
swagger、graphql 都可以帮助我们生成后端控制器的定义，明确后端参数及返回是 低代码、可视化表单及页面 的核心功能。 而 swagger、graphql 在提供了文档的同时，也带来了一些问题，比如维护成本高、文档不准确等，这导致在现实相当大一部分程序员或者公司无力承担这样的成本。 opss 的推断能力为我们的稳固代码质量，降低开发成本的同时为开发模式同样提供了无限的可能性。
opss 相比于 swagger
| 特性 | opss | swagger |
|---|---|---|
| 样板代码 | 默认 0 代码 | 大量样板代码 |
| 初始化工作量 | 仅相当于 swagger 的 1/10，一般只需要对 controller 的名称描述 | 代码量大，维护成本高 |
| 后续维护 | 自动化，输入、输出 参数全自动更新，可准确联想所使用到的 enum、interface 更新建模并自动引用，对 type 自动更新 | 随着代码变更，文档需要手动维护且可能导致不准确。 |
| 扩展能力 | 帮助用户收集控制器信息，用户可根据控制器信息，自主扩展功能。比如带有 @UseGuards(JwtAuthGuard) 需要添加 Authorization 头 | 随着代码变更，文档需要手动维护且可能导致不准确。 |
| 未来规划 | 云平台协作功能正在全职开发、将会提供更多的便利功能。 | - |
opss 相比于 swagger 的工作量对比
import { Controller, Post, Body, UploadedFiles, UseInterceptors } from '@nestjs/common';
import { FileFieldsInterceptor } from '@nestjs/platform-express';
import { Express } from 'express';
@Controller('my') // 路由前缀
class MyController {
@Post('upload-fields')
@UseInterceptors(FileFieldsInterceptor([
{ name: 'avatar', maxCount: 1 },
{ name: 'background', maxCount: 1 },
]))
async uploadFileFields(
@Body() body: { name: string },
@UploadedFiles() files: { avatar?: Express.Multer.File[], background?: Express.Multer.File[] }
) {
// 执行上传
return {
code: 0,
message: '上传成功',
data: {
avatar: files.avatar?.[0].filename,
background: files.background?.[0].filename,
}
};
}
}
export { MyController };