使用 Swagger-Express-TS 快速构建REST API

使用 Swagger-Express-TS 快速构建REST API

swagger-express-tsGenerate and serve swagger.json项目地址:https://gitcode.com/gh_mirrors/sw/swagger-express-ts

Swagger-Express-TS 是一个强大的Node.js中间件，专为使用Express框架的TypeScript项目设计，旨在简化RESTful API的开发与文档化。它整合了Tsoa和Swagger UI，自动为你生成符合OpenAPI规范的文档，让你的API开发过程更加高效且文档保持同步更新。

项目介绍

Swagger-Express-TS 提供了一个简洁的方式去添加Swagger（现在称为OpenAPI）规范到你的Express应用程序中。通过使用装饰器和TypeScript的类型系统，它帮助开发者定义清晰的服务接口，并自动生成交互式的API文档，方便团队协作和外部调用者理解。此外，它支持实时更新文档，提高了开发效率。

项目快速启动

环境准备

确保你已经安装了Node.js (建议v14+), 并且设置了Node环境。

初始化项目

首先，创建一个新的Node.js项目：

mkdir swagger-express-ts-demo
cd swagger-express-ts-demo
npm init -y

然后，安装必要的依赖：

npm install express @tsconfig/node14@latest tsoa swagger-ui-express --save
npm install concurrently @types/express @types/swagger-ui-express @types/node --save-dev

配置TsConfig

编辑 tsconfig.json 文件以启用装饰器的支持：

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "lib": ["es6", "dom"],
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "实验性装饰器": true,
    "emitDecoratorMetadata": true
  },
  "include": ["src/**/*"]
}

添加Tsoa配置

在根目录下创建 tsoa.json 配置文件:

{
  "entryFile": "src/index.ts",
  "spec": {
    "outputDirectory": "public",
    "specVersion": 3
  }
}

编写基本服务

在 src 目录下创建 index.ts :

import express from 'express';
import { RouteController } from './routes'; // 假设你有RouteController类
import * as swaggerUI from 'swagger-ui-express';

const app = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());
app.use('/api/docs', swaggerUI.serve, swaggerUI.setup(null, {
  url: '/api/docs/swagger.json',
}));

// 引入路由
app.use('/api', RouteController);

// 启动服务器
app.listen(PORT, () => {
  console.log(`Server is running on http://localhost:${PORT}`);
});

自动生成Swagger文档

修改 package.json 添加脚本命令用于生成和查看文档：

"scripts": {
  "start": "tsc && node dist",
  "dev": "concurrently \"tsc -w\" \"nodemon\"",
  "swagger": "tsoa spec"
},

运行并验证

• 先运行 npm run swagger 生成初始的Swagger JSON。
• 接着运行 npm run dev 开始开发模式，这将自动编译TypeScript并监视变化。
• 访问 http://localhost:3000/api/docs 查看并测试你的API文档。

应用案例和最佳实践

• 模型驱动: 利用TypeScript的强类型定义你的数据模型和接口。
• 装饰器使用: 在控制器和方法上使用Tsoa提供的装饰器来明确路径、请求方式及响应结构。
• 版本控制: 可通过不同的路径前缀或查询参数管理API的不同版本。
• 错误处理: 实现统一的错误处理机制，确保API响应一致性。

典型生态项目

虽然给出的示例是基于特定的GitHub仓库链接简化而来，但实际生态中，类似的项目还包括如Fastify结合OpenAPI的解决方案，以及对于其他Node.js框架的类似插件，这些都旨在提升API开发的标准化和文档化水平。利用Swagger-UI作为前端，可以轻松集成到任何支持开放API规范的后端服务中，促进了跨团队的沟通与合作。

---

通过遵循以上步骤，你可以迅速地在Express应用中搭建起一套完善的REST API服务，伴随详细的文档，使得服务更加健壮且易于维护。

swagger-express-tsGenerate and serve swagger.json项目地址:https://gitcode.com/gh_mirrors/sw/swagger-express-ts