routing-controllers-openapi 使用指南

routing-controllers-openapi 使用指南

1. 项目目录结构及介绍

在 routing-controllers-openapi 这个开源项目中，核心的结构设计围绕着构建基于 TypeScript 的 RESTful API，并通过 OpenAPI 规范提供接口文档。以下是一个典型的基本结构概览：

• src

  • 包含应用的主要源代码，比如控制器(Controller)，服务(Service)，以及可能的模型(Model)。
    • controllers: 存放处理业务逻辑和路由请求的控制器类，例如 UsersController.ts。

• sample

  • 示例应用目录，展示了如何集成与使用这个库。
    • 01-basic
      • 入门示例，包括基本的设置文件如 app.ts，展示基础配置与启动流程。

• 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 开源项目关键部分的简单介绍与说明，旨在帮助快速理解和上手该框架。实际使用时，应详细阅读官方文档获取更全面的开发指南。