受 TypeScript 启发,微软又搞了一个神器!

开发 前端
TypeSpec[1] 是一种高度可扩展的语言,可轻松描述 REST、OpenAPI、gRPC 和其他协议中常见的 API 结构。TypeSpec 在生成多种不同的 API 描述格式、客户端和服务端代码、文档等方面表现出色。

TypeSpec 是什么

图片

TypeSpec[1] 是一种高度可扩展的语言,可轻松描述 REST、OpenAPI、gRPC 和其他协议中常见的 API 结构。TypeSpec 在生成多种不同的 API 描述格式、客户端和服务端代码、文档等方面表现出色。有了 TypeSpec,你就可以摆脱那些拖慢你速度的手写文件,并在几秒钟内生成符合标准的 API Schemas。

TypeSpec 的特点

  • 简洁轻量:受 TypeScript 的启发,TypeSpec 是一种极简语言,可帮助开发人员以熟悉的方式描述 API。
  • 易集成:编写 TypeSpec,发布为各种格式,快速与其它生态系统集成。
  • 支持多种协议:TypeSpec 标准库支持主流的 OpenAPI 3.0,JSON Schema 2020-12,Protobuf,和 JSON RPC 等协议。
  • 功能强大:受益于庞大的 OpenAPI 工具生态系统,可用于配置 API 网关、生成代码和验证数据。
  • 保证数据一致性:定义要在 API 中使用的通用模型,使用 JSON Schema 发射器获取类型的 JSON Schema,并使用它们验证数据。
  • 友好的开发体验:在 VSCode 和 Visual Studio 编辑器中为了 TypeSpec 提供了全面的语言支持。比如,语法高亮、代码补全等功能。

TypeSpec 使用示例

生成 OpenAPI 描述文件

图片图片

生成 JSON Schema

图片图片

生成 Protobuf

图片图片

TypeSpec Playground

要快速体验 TypeSpec 的功能,推荐你使用 TypeSpec 官方提供的 playground[2]。该 playground 预设了 API versioning、Discriminated unions、HTTP service、REST framework、Protobuf Kiosk 和 Json Schema 6 个不同的使用示例,并支持 File 和 Swagger UI 两种视图。

File 视图

图片图片

Swagger UI 视图

图片图片

TypeSpec 快速上手

1.安装 @typespec/compiler 编译器

npm install -g @typespec/compiler

2.安装 VSCode 扩展

在 VSCode 中搜索 TypeSpec 安装 TypeSpec for VS Code 扩展,或在浏览器中打开 TypeSpec for VS Code[3] 网址后点击 Install 按钮。

3.创建 TypeSpec 项目

首先新建一个新的目录,然后在项目的根目录下执行以下命令:

tsp init

图片图片

图片图片

4.安装项目依赖

tsp install

成功执行上述命令后,在当前目录下会生成以下目录结构:

.
├── main.tsp
├── node_modules
├── package-lock.json
├── package.json
└── tspconfig.yaml

之后,打开 main.tsp 文件,输入以下代码:

import "@typespec/http";

using TypeSpec.Http;
@service({
  title: "Widget Service",
})
namespace DemoService;

model Widget {
  @visibility("read", "update")
  @path
  id: string;

  weight: int32;
  color: "red" | "blue";
}

@error
model Error {
  code: int32;
  message: string;
}

@route("/widgets")
@tag("Widgets")
interface Widgets {
  @get list(): Widget[] | Error;
  @get read(@path id: string): Widget | Error;
  @post create(...Widget): Widget | Error;
  @patch update(...Widget): Widget | Error;
  @delete delete(@path id: string): void | Error;
  @route("{id}/analyze") @post analyze(@path id: string): string | Error;
}

完成输入后,运行 tsp compile . 命令执行编译操作。成功编译后,在 tsp-output/@typespec/openapi3 目录下就会生成 openapi.yaml 文件:

图片图片

有关 TypeSpec 的相关内容就介绍到这里,如果你想进一步了解 TypeSpec 的基础使用和高级用法,推荐你阅读官方的使用文档[4]。

参考资料

[1]TypeSpec: https://typespec.io/

[2]playground: https://typespec.io/playground

[3]TypeSpec for VS Code: https://marketplace.visualstudio.com/items?itemName=typespec.typespec-vscode

[4]使用文档: https://typespec.io/docs

责任编辑:武晓燕 来源: 全栈修仙之路
相关推荐

2024-01-22 09:28:27

2023-09-01 08:53:52

后端优化开发

2022-07-04 10:40:35

Jinja2代码生成器模板语言

2022-03-23 18:00:34

循环CPU线程

2021-06-02 06:14:50

Nyxt浏览器

2013-07-12 10:18:39

微软CEO鲍尔默微软

2023-11-22 08:26:03

HutoolJava工具集

2020-01-20 14:40:39

工具代码开发

2015-03-19 10:26:50

2023-11-09 09:02:26

TypeScriptas const

2023-05-14 23:38:43

Glarity用户视频

2022-02-06 20:55:39

jsEsbuild项目

2015-07-01 18:18:39

网络中断

2021-09-24 09:15:19

Windowsfx 1LinuxWindows 11

2024-04-02 09:42:39

2021-08-19 09:00:12

监控文件Python

2022-09-28 10:35:31

JavaScript代码内存泄漏

2010-12-05 19:03:39

TechEd 2010

2016-06-05 17:13:36

博科/网络自动化

2021-10-16 07:31:54

微信深度清理腾讯
点赞
收藏

51CTO技术栈公众号