@airtasker/spot

中文文档

2.0.0发布于 2026/01/28MITTypeScriptCommonJS近 30 天下载 5841

点 (单位:千美元)"真理的单一点")是一种简洁,开发者友好的方式来描述你的API合同.

文档目录16 节

开始
所需资源
安装
书面合同
审查合同
不同格式的互操作性
在记忆使用中
spot checksum SPOT_CONTRACT
spot docs SPOT_CONTRACT
spot generate
spot help [COMMAND]
spot init
spot lint SPOT_CONTRACT
spot mock SPOT_CONTRACT
spot validate SPOT_CONTRACT
spot validation-server SPOT_CONTRACT

点

点 (单位:千美元)"真理的单一点")是一种简洁,开发者友好的方式来描述你的API合同.

使用 TypeScript 语法,它允许您描述您的 API 并生成您需要的其他 API 合同格式( OpenAPI, Swagger, JSON Schema) .

您不需要使用代码库中的 TypeScript 来获益于使用 Spot .

API 定义文件示例 api.ts 定义单个 POST 创建用户的结束点 :

import { api, endpoint, request, response, body } from "@airtasker/spot";

@api({
  name: "My API"
})
class Api {}

@endpoint({
  method: "POST",
  path: "/users"
})
class CreateUser {
  @request
  request(@body body: CreateUserRequest) {}

  @response({ status: 201 })
  response(@body body: CreateUserResponse) {}
}

interface CreateUserRequest {
  firstName: string;
  lastName: string;
}

interface CreateUserResponse {
  firstName: string;
  lastName: string;
  role: string;
}

开始

从写Spot合同开始点点指南

关于所有可用的语法,参见斑点语法

所需资源

节点.js >= 18.12.0
pnpm( 建议) 或 npm

安装

与小时安装并初始化 @airtasker/spot 对您的项目:

pnpm add @airtasker/spot

只需运行即可将上面的定义传递给生成器 :

npx @airtasker/spot generate --contract api.ts

为什么我们造出斑点

乍一看,你可能会想知道为什么我们打扰建筑点。为什么不使用OpenAPI(形式上称为Swagger)来描述您的API?

在核心,我们建造了Spot,因为我们想要更好的开发者经验.

书面合同

OpenAPI文档作为YAML文件存储,遵循非常具体的计划. 您不会知道您使用错误的字段名称, 或忘记将类型定义包装到一个计划对象中, 除非您运行一个好的 OpenAPI linter 。大多数不熟悉 OpenAPI 规格的开发者最终使用Swagger 编辑器或 Stoplight 等视觉编辑器.

由于 Spot 调用 TypeScript 语法,你只需要写出有效的 TypeScript 代码. 当您的代码无效时, 您的编辑会立即告诉你。它会告诉你缺少什么,你甚至可以免费自动完成。我们本来可以选择任何其他类型的语言——TypeScript恰好是我们最简洁和无所不在的语言之一.

审查合同

我们认为API合同应该被检查到Git,或者任何你使用的代码版本系统. 此外,应系统地审查API合同。后端工程师很难错误地假设客户工程师对终点的期望.

由于其复杂的嵌入式结构以及OpenAPI规格的丰富性,OpenAPI文档在拉出请求中可能难以审查. 他们擅长机器.

Spot旨在尽可能能被人类读取. 与我们先前的OpenAPI文件相比.

不同格式的互操作性

根据您想要达到的目标(测试,文档,客户端代码生成...),您会找到只和OpenAPI 2(Swagger)合作的工具,以及仅支持OpenAPI 3的更新的工具. 您也可以为不同的 API 生态系统找到工具, 如 JSON Schema 或 API 蓝图 .

我们建Spot就是考虑到这一点。 Spot不需将各种API格式转换器相拼,而是可以生成出每个主要的API文档格式. 这就是为什么我们称之为"真理的单一点".

点
为什么我们造出斑点
使用量
图标

使用量

要在当前目录中启动并设置 API 声明, 运行 :

npx @airtasker/spot init

然后,您可以用 :

npx @airtasker/spot generate --contract api.ts

在记忆使用中

import { Spot } from "@airtasker/spot";

const contract = Spot.parseContract("./api.ts")
const openApi = Spot.OpenApi3.generateOpenAPI3(contract);

console.log(openApi);

/*
{
  openapi: '3.0.2',
  info: { title: 'my-api', description: undefined, version: '0.0.0' },
  paths: { '/users': { post: [Object] } },
  components: {
    schemas: { CreateUserRequest: [Object], CreateUserResponse: [Object] },
    securitySchemes: undefined
  },
  security: undefined
}
*/

图标

spot checksum SPOT_CONTRACT
spot docs SPOT_CONTRACT
spot generate
spot help [COMMAND]
spot init
spot lint SPOT_CONTRACT
spot mock SPOT_CONTRACT
spot validate SPOT_CONTRACT
spot validation-server SPOT_CONTRACT

`spot checksum SPOT_CONTRACT`

为 Spot 合同生成支票和

USAGE
  $ spot checksum SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot checksum api.ts

参见代码 : 构建/cli/src/命令/校验和.js

`spot docs SPOT_CONTRACT`

预览 Spot 合同作为 OpenAPI3 文档。文件服务器将在http://localhost:8080上启动.

USAGE
  $ spot docs SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 8080] Documentation server port

EXAMPLE
  $ spot docs api.ts

参见代码 : 构建/cli/src/命令/docs.js

`spot generate`

运行 API 上的生成器。曾出产客户端库,服务器锅炉板和OpenAPI等知名API合同格式.

USAGE
  $ spot generate

OPTIONS
  -c, --contract=contract    (required) Path to a TypeScript Contract definition
  -g, --generator=generator  Generator to run
  -h, --help                 show CLI help
  -l, --language=language    Language to generate
  -o, --out=out              Directory in which to output generated files

EXAMPLE
  $ spot generate --contract api.ts --language yaml --generator openapi3 --out output/

参见代码 : 构建/ cli/ src/ commands/ generate.js

`spot help [COMMAND]`

显示点名帮助

USAGE
  $ spot help [COMMAND]

ARGUMENTS
  COMMAND  command to show help for

OPTIONS
  --all  see all commands in CLI

参见代码 : @oclif/plugin-帮助

`spot init`

生成锅炉板用于API.

USAGE
  $ spot init

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot init
  Generated the following files:
  - api.ts
  - tsconfig.json
  - package.json

参见代码 : 构建/cli/src/命令/init.js

`spot lint SPOT_CONTRACT`

定点合同

USAGE
  $ spot lint SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help                                                     show CLI help
  --has-discriminator=(error|warn|off)                           Setting for has-discriminator
  --has-request-payload=(error|warn|off)                         Setting for has-request-payload
  --has-response=(error|warn|off)                                Setting for has-response
  --has-response-payload=(error|warn|off)                        Setting for has-response-payload
  --no-inline-objects-within-unions=(error|warn|off)             Setting for no-inline-objects-within-unions
  --no-nullable-arrays=(error|warn|off)                          Setting for no-nullable-arrays
  --no-nullable-fields-within-request-bodies=(error|warn|off)    Setting for no-nullable-fields-within-request-bodies
  --no-omittable-fields-within-response-bodies=(error|warn|off)  Setting for no-omittable-fields-within-response-bodies
  --no-trailing-forward-slash=(error|warn|off)                   Setting for no-trailing-forward-slash

EXAMPLES
  $ spot lint api.ts
  $ spot lint --has-descriminator=error
  $ spot lint --no-nullable-arrays=off

参见代码 : 构建/cli/src/命令/lint.js

`spot mock SPOT_CONTRACT`

根据 Spot 合同运行一个模拟服务器

USAGE
  $ spot mock SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help                                   show CLI help
  -p, --port=port                              (required) [default: 3010] Port on which to run the mock server
  --pathPrefix=pathPrefix                      Prefix to prepend to each endpoint path

  --proxyBaseUrl=proxyBaseUrl                  If set, the server will act as a proxy and fetch data from the given
                                               remote server instead of mocking it

  --proxyFallbackBaseUrl=proxyFallbackBaseUrl  Like proxyBaseUrl, except used when the requested API does not match
                                               defined SPOT contract. If unset, 404 will always be returned.

  --proxyMockBaseUrl=proxyMockBaseUrl          Like proxyBaseUrl, except used to proxy draft endpoints instead of
                                               returning mocked responses.

EXAMPLE
  $ spot mock api.ts

参见代码 : 构建/cli/src/命令/mock.js

`spot validate SPOT_CONTRACT`

验证Spot合同

USAGE
  $ spot validate SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help  show CLI help

EXAMPLE
  $ spot validate api.ts

参见代码 : 构建/ cli/ src/ 命令/ 验证.js

`spot validation-server SPOT_CONTRACT`

启动现场合同验证服务器

USAGE
  $ spot validation-server SPOT_CONTRACT

ARGUMENTS
  SPOT_CONTRACT  path to Spot contract

OPTIONS
  -h, --help       show CLI help
  -p, --port=port  [default: 5907] The port where application will be available

EXAMPLE
  $ spot validation-server api.ts

参见代码 : 构建/cli/src/命令/验证-服务器.js

版本与发布记录

@airtasker/spot 共发布 50 个版本，首次发布于 2018/11/27；过去 12 个月发布了 1 个版本。

版本	发布日期	距今
`2.0.0`latest	2026/01/28	9 个月前
`1.13.0`	2023/11/20	2 年前
`1.12.0`	2023/10/12	3 年前
`1.11.0`	2023/10/05	3 年前
`1.10.0`	2023/10/04	3 年前
`1.9.0`	2021/06/23	5 年前

关于 @airtasker/spot 的常见问题

@airtasker/spot 是什么？

点 (单位:千美元)"真理的单一点")是一种简洁,开发者友好的方式来描述你的API合同.

如何安装 @airtasker/spot？

在项目目录运行 npm install @airtasker/spot，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 spot，可以用 npx spot 直接运行。

@airtasker/spot 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@airtasker/spot 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@airtasker/spot 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=18.12.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@airtasker/spot 可以商用吗？

@airtasker/spot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@airtasker/spot 的下载量有多少？

根据 npm 官方下载统计，@airtasker/spot 在 2026/10/05 – 2026/11/03 这 30 天内被下载 5,841 次，日均约 195 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@airtasker/spot 还在维护吗？

最新版本 2.0.0 发布于 2026/01/28（9 个月前）；至今共发布 50 个版本，其中过去 12 个月发布了 1 个；首次发布于 2018/11/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。