npm 包 tsoa-extension 使用教程-JavaScript中文网-JavaScript教程资源分享门户

概述

tsoa-extension 是一款面向 TypeScript 应用程序中的 API 开发者的 npm 包，它可以自动生成标准化的 OpenAPI 规范的文档，使得前端开发人员可以更加便利地在应用程序之间通信、调试和部署。与传统的文档生成工具不同， tsoa-extension 独有的特点在于其可以自动识别 TypeScript 代码中的装饰器，从而根据修饰符自动生成相应的 Restful API 接口。

本文将详细介绍如何在前端应用程序中使用 tsoa-extension 生成 OpenAPI 规范的 API 文档，并针对部分细节问题做相应的解析。

安装和配置

使用 tsoa-extension 前，需要先安装和配置相关环境和工具。具体如下：

1. 安装 node.js 和 npm

在官网 https://nodejs.org/en/ 中下载安装的二进制文件，即可安装 node.js 和 npm，并进行验证：

$ node -v
vXX.XX.X
$ npm -v
X.X.X

2. 初始化 TypeScript 项目

首先，使用 npm 初始化一个 TypeScript 项目：

$ mkdir tsoa-demo && cd tsoa-demo
$ npm init

接着，安装 TypeScript 和 ts-node：

$ npm install typescript ts-node

并将 tsconfig.json 文件添加到项目根目录下：

-- -------------------- ---- -------
-
    ------------------ -
        --------- ------
        --------- -----------
        --------- -------
        --------- -----
        ------------------ ----
    --
    ---------- -
        --------------
    -
-

3. 安装和配置 tsoa

使用 npm 安装 tsoa 依赖包：

$ npm install tsoa

并创建相关的控制器、 models 和 API 路由。这里以一个简单的示例为例：

-- -------------------- ---- -------
------ - ----------- ---- ------ ---- - ---- -------

--------- ---- -
    ----- -------
    ---- -------
-

----------------
--------------
------ ----- -------------- ------- ---------- -
    -----------------
    ------ ----- --------------- -------- ------------- -
        ------ -
            ----- -----
            ---- ---
        --
    -
-

这段代码定义了一个 /users/{userId} 路由，返回类型为 User 的对象。注意，这里的路由是根据 http 协议规范定义的，既包括请求方式（如 GET 或 POST），也包括相应的路径和参数。

4. 安装和配置 jest

使用 npm 安装测试和断言库 jest 的依赖包：

$ npm install jest ts-jest @types/jest

并添加 jest.config.js 文件：

module.exports = {
  preset: "ts-jest",
  testEnvironment: "node",
  testMatch: ["**/?(*.)+(spec|test).[jt]s?(x)"],
};

这里设置 testEnvironment 为 node，testMatch 匹配带有 spec 或者 test 的文件。

5. 安装和配置 tsoa-extension

为了安装 tsoa-extension 包，使用如下命令：

$ npm install tsconfig-paths tsoa-extension

这里我们使用 tsconfig-paths 管理前端 TypeScript 代码路径，避免使用 ../ 等相对路径。

接着，在 package.json 中加入以下信息：

-- -------------------- ---- -------
-
  ------- ------------------
  ---------- -
    -------- ----- ------ -- -----
    -------- ---- ---------------- -- ---- ---
    ------- ----- ------------------- ----------- ---------- ----------------------
  --
  ------- -
    ------------ -------------
    ----------- ----------------
    ------------------ -------
    ------------ ------------
  -
-

注意，这里的配置与 tsoa 相关，其中 routesDir 指定 API 路由所在的目录， yamlPath 指定输出的 OpenAPI 文档路径， outputDirectory 指定打包后的代码所在的目录， entryFile 指定应用入口文件。

使用

配置完环境后，我们就可以使用 tsoa-extension 工具来生成 OpenAPI 规范的 API 文档了。详细的使用方法如下：

在项目根目录下生成 tsoa.json 配置文件：
```
$ ./node_modules/.bin/tsoa --spec
```
生成 API 代码和路由文件：
```
$ npm run build
```
启动后端服务，验证 API 接口返回是否正确：
```
$ npm run start
```
在浏览器中打开 http://localhost:3000/docs，验证 OpenAPI 文档能够成功加载。

注意，这里需要把 localhost:3000 替换成你的应用程序运行地址。如果一切正常，你应该就能看到类似下面的一幕：

总结

通过本文，我们了解了如何使用 npm 包 tsoa-extension 来生成 OpenAPI 规范的 API 文档，以及在使用过程中的注意事项。希望这些内容对前端开发人员有所启发，可以帮助读者更加快捷和高效地在应用程序之间进行调试和部署。如果你对本文有任何疑问或者建议，欢迎随时在下方留言区发表你的评论和建议。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/600572c581e8991b448e8e67