在Ts.ED项目中使用Scalar构建API文档指南

在Ts.ED项目中使用Scalar构建API文档指南

tsed :triangular_ruler: Ts.ED is a Node.js and TypeScript framework on top of Express to write your application with TypeScript (or ES6). It provides a lot of decorators and guideline to make your code more readable and less error-prone. ⭐️ Star to support our work! 项目地址: https://gitcode.com/gh_mirrors/ts/tsed

前言

在现代Web开发中，良好的API文档是项目成功的关键因素之一。Ts.ED作为一个基于TypeScript的Node.js框架，提供了与Scalar API文档工具的无缝集成方案。本文将详细介绍如何在Ts.ED项目中配置和使用Scalar来生成美观且功能强大的API文档。

Scalar简介

Scalar是一个现代化的API文档工具，它基于OpenAPI规范，能够自动生成交互式的API文档界面。与Ts.ED框架结合使用时，开发者可以利用现有的装饰器来构建符合OpenAPI规范的API描述，无需额外编写大量文档代码。

环境准备

安装依赖

首先需要安装必要的依赖包：

npm install --save @tsed/scalar

基础配置

在Ts.ED项目的服务端配置中添加Scalar模块：

import {Configuration} from "@tsed/common";
import "@tsed/platform-express";
import "@tsed/scalar";

@Configuration({
  scalar: [
    {
      path: "/doc",  // 文档访问路径
      specVersion: "3.0.1"  // OpenAPI规范版本
    }
  ]
})
export class Server {}

配置完成后，文档将可以通过http://localhost:8000/doc访问，启动服务时控制台会打印具体的访问URL。

安全配置注意事项

当项目中使用helmet中间件时，可能会遇到内容安全策略(CSP)相关问题。以下是解决方案：

调整CSP策略

@Configuration({
  middlewares: [
    helmet({
      contentSecurityPolicy: {
        directives: {
          defaultSrc: [`'self'`],
          styleSrc: [`'self'`, `'unsafe-inline'`],
          imgSrc: [`'self'`, "data:", "validator.scalar.io"],
          scriptSrc: [`'self'`, `https: 'unsafe-inline'`]
        }
      }
    })
  ]
})
export class Server {}

完全禁用CSP

@Configuration({
  middlewares: [
    helmet({
      contentSecurityPolicy: false
    })
  ]
})
export class Server {}

高级配置选项

Scalar模块提供了丰富的配置选项，以下是主要配置项说明：

| 配置项 | 类型 | 说明 | |----------------------|------------|----------------------------------------------------------------------| | path | string | 文档访问路径，默认为/api-doc | | specVersion | string | OpenAPI规范版本，如3.0.1 | | cdn | string | 自定义Scalar资源CDN地址 | | fileName | string | 生成的OpenAPI文件名，默认为openapi.json | | doc | string | 文档标识，用于创建多个文档 | | viewPath | string | 自定义视图模板路径 | | cssPath | string | 自定义CSS文件路径 | | showExplorer | boolean | 是否显示搜索栏，默认为true | | spec | object | 默认的OpenAPI规范信息 | | specPath | string | 从指定路径加载基础规范文档 | | outFile | string | 将规范文档写入指定路径 | | hidden | boolean | 是否在资源列表中隐藏文档 | | options | object | Scalar原生选项 | | operationIdFormatter | function | 自定义操作ID生成函数 | | operationIdPattern | string | 操作ID生成模式，如%c_%m（%c:类名，%m:方法名） | | pathPatterns | string[] | 包含匹配指定路径模式的控制器 | | sortPaths | boolean | 是否按字母顺序排序路径，默认为true |

自定义Scalar版本

如果需要指定特定版本的Scalar包：

@Configuration({
  scalar: [
    {
      path: "/doc",
      cdn: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@x.y.z"
    }
  ]
})
export class Server {}

多文档管理

通过装饰器实现

Ts.ED支持创建多个API文档，并通过@Docs装饰器指定控制器所属文档：

@Configuration({
  scalar: [
    {
      path: "/doc",
      doc: "default"
    },
    {
      path: "/doc-private",
      doc: "private"
    }
  ]
})
export class Server {}

@Controller("/")
@Docs("default")
export class MyController {
  @Get("/")
  get() {
    return {hello: "world"};
  }
}

通过路径模式实现

也可以使用路径模式来组织文档：

@Configuration({
  scalar: [
    {
      path: "/api-admin",
      pathPatterns: ["/rest/admin/**"]
    },
    {
      path: "/api-all",
      pathPatterns: ["!/rest/admin/**"]
    }
  ]
})
export class Server {}

模型文档化

Ts.ED支持基于JsonSchema的模型定义，这些模型可以自动出现在API文档中：

import {Property, Required} from "@tsed/schema";

class MyModel {
  @Property()
  @Required()
  id: string;

  @Property()
  value: number;
}

@Controller("/models")
export class MyController {
  @Post("/")
  post(@BodyParams() model: MyModel) {
    return model;
  }
}

端点文档化

通过装饰器可以详细描述API端点：

@Controller("/users")
export class UsersController {
  @Get("/:id")
  @Summary("获取用户信息")
  @Returns(200, User).Description("成功返回用户信息")
  async get(
    @PathParams("id") @Description("用户ID") id: string
  ): Promise<User> {
    // 实现代码
  }
}

额外参数文档

对于不直接使用的参数（如某些头部信息），可以使用@In装饰器进行文档化：

@Controller("/")
export class MyController {
  @Get("/")
  @In("header").Name("x-token").Description("认证token").Required(false)
  get() {
    return {hello: "world"};
  }
}

拦截规范生成

通过$alterOpenSpec钩子可以在规范生成后、返回给客户端前进行修改：

@Configuration()
class Server {
  $alterOpenSpec(spec: OpenSpec, config: SwaggerSettings) {
    // 修改spec对象
    return spec;
  }
}

结语

通过Ts.ED与Scalar的集成，开发者可以轻松创建专业级的API文档，同时保持代码与文档的同步。本文介绍了从基础配置到高级用法的完整流程，希望能帮助您在项目中更好地使用这一强大组合。

tsed :triangular_ruler: Ts.ED is a Node.js and TypeScript framework on top of Express to write your application with TypeScript (or ES6). It provides a lot of decorators and guideline to make your code more readable and less error-prone. ⭐️ Star to support our work! 项目地址: https://gitcode.com/gh_mirrors/ts/tsed