routing-controllers-openapi 使用指南
1. 项目目录结构及介绍
在 routing-controllers-openapi
这个开源项目中,核心的结构设计围绕着构建基于 TypeScript 的 RESTful API,并通过 OpenAPI 规范提供接口文档。以下是一个典型的基本结构概览:
-
src
- 包含应用的主要源代码,比如控制器(Controller),服务(Service),以及可能的模型(Model)。
- controllers: 存放处理业务逻辑和路由请求的控制器类,例如
UsersController.ts
。
- controllers: 存放处理业务逻辑和路由请求的控制器类,例如
- 包含应用的主要源代码,比如控制器(Controller),服务(Service),以及可能的模型(Model)。
-
sample
- 示例应用目录,展示了如何集成与使用这个库。
- 01-basic
- 入门示例,包括基本的设置文件如
app.ts
,展示基础配置与启动流程。
- 入门示例,包括基本的设置文件如
- 01-basic
- 示例应用目录,展示了如何集成与使用这个库。
-
node_modules
- 项目的依赖包所在目录,自动管理安装的第三方库如
class-validator
,routing-controllers
等。
- 项目的依赖包所在目录,自动管理安装的第三方库如
-
package.json
- 项目配置文件,记录了项目的元数据,脚本命令,依赖等信息。
-
tsconfig.json(假设存在)
- TypeScript 编译配置文件,指导TypeScript编译过程中的各种选项设置。
2. 项目的启动文件介绍
启动文件主要位于示例目录下,如 sample/01-basic/app.ts
。此文件是应用的入口点,负责初始化服务器并配置路由控制器。关键步骤包括:
- 引入必要的模块,如
Express
,class-validator-jsonschema
,routing-controllers
,routing-controllers-openapi
, 和swagger-ui-express
。 - 配置元数据存储(
defaultMetadataStorage
)用于class-validator
和class-transformer
。 - 创建路由控制器服务器,通过
createExpressServer
函数,并指定控制控制器类。 - 将控制器类转换为 OpenAPI 规范,通过
routingControllersToSpec
方法,这一步将所有定义的路由和验证规则转化为OpenAPI规范的一部分。 - 设置 Swagger UI,方便查看和测试API文档,使用
swaggerUiExpress
模块。 - 启动 Express 服务器监听特定端口,并挂载 OpenAPI 文档路径。
3. 项目的配置文件介绍
在这个特定的开源项目中,配置主要是通过代码方式进行的,而不是传统的外部配置文件。重要配置片段通常包含在启动文件(app.ts
)或是在导入的路由控制器选项对象中。以 app.ts
中的配置为例:
-
Routing Controllers Options (
routingControllersOptions
):这里定义了控制器数组,指定哪些控制器被路由使用,以及可选的前缀(routePrefix
)来统一API路径前缀。 -
OpenAPI Spec Generation:通过
routingControllersToSpec
函数参数来配置OpenAPI规格,例如添加组件(如JSON Schema)、安全方案(如Basic Auth)以及信息对象(标题、版本描述等)。
虽然没有独立的配置文件如.json
或.yaml
形式存在,但在进行项目配置时,开发者会在代码中动态地设定这些参数,实现定制化需求。
以上就是对 routing-controllers-openapi
开源项目关键部分的简单介绍与说明,旨在帮助快速理解和上手该框架。实际使用时,应详细阅读官方文档获取更全面的开发指南。