【从0到发布】写一个将阿里云OpenAPI转换成Typescript的VSCode插件

TEL哈迪斯
526 阅读4分钟

前言

最近在做老项目的部分重构，将JS转换为TS，页面中的大部分的数据类型都是从API接口来的，所以将接口请求和响应的数据转化为TS类型就很有必要。而我当前负责开发的产品是在公共云上，接口大部分都开通了OpenAPI，从而考虑将OpenAPI的文档数据转换为TS类型，减少书写TS类型的时间。又因为使用VSCode作为开发编辑器，所以考虑开发一个VSCode插件，以便在VSCode上直接使用生成的TS代码。

下面是记录下开发这个插件的过程，跟大家一起学习，并且多多指教。项目地址，插件地址

一、开发

1. 创建项目

首先参考VSCode拓展开发的官方手册，运行下面的命令创建项目：

npx --package yo --package generator-code -- yo code

2. 代码开发

2.1 获取OpenAPI文档数据

首先需要获取到阿里云的OpenAPI文档数据。在阿里云API官方首页有一个搜索框，在这里可以搜索到阿里云全站的所有OpenAPI，打开调试，输入CreateInstance，可以看出有这么一个接口的请求：https://api.aliyun.com/api/search/api?query=CreateInstance&query_type=direct&biz=workbench_home&page=1&perPage=20&guess_tab=1 image.png 它满足对阿里云OpenAPI搜索的要求，基于这个接口可以获取到满足条件的API数据列表。再根据阿里云开放的GetApiInfo接口获取具体API的JSONSchema数据，将JSONSchema数据转换为TS类型数据，具体转换逻辑就不在这边赘述，可以在项目中查看。

还可以根据GetAPIDocs接口一次性获取固定产品和日期版本下的所有API列表。

2.2 插件开发

知道怎么获取数据后，开始插件的开发，首先在src/extension.ts中的activate方法中注册一个命令:

import * as vscode from 'vscode';
import { genInterface } from './genInterface';

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand(
    'alibaba-cloud-api-to-typescript.AlibabaCloudAPIToTypescript',
    () => {
      genInterface();
    },
  );
  context.subscriptions.push(disposable);
}

也需要在package.json文件中添加命令：

"contributes": {
    "commands": [
      {
        "command": "alibaba-cloud-api-to-typescript.AlibabaCloudAPIToTypescript",
        "title": "Alibaba Cloud API To Typescript"
      }
    ],
}

通过该命令来激活插件。开发过程中可以在项目中按F5启动调试。

使用 vscode.window.createQuickPick() 方法创建一个可远程搜索的选择框，将通过接口获取的API列表数据展示出来，再将选中的具体API数据转换为TS代码，将TS代码输出并展示在新窗口。通过以下代码实现：

const document = await vscode.workspace.openTextDocument({ content: '', language: 'typescript' });
const editor = await vscode.window.showTextDocument(document);
// 插入代码
editor.edit((editBuilder) => {
    editBuilder.insert(new vscode.Position(0, 0), value); // value为生成的ts代码
});

具体实现逻辑可查看src/genInterface.ts文件。

到这一步，插件就已经开发完成，但是为了丰富插件的功能，添加了一些配置选项。在package.json中增加contributes.configuration:

"contributes": {
    "commands": [
      {
        "command": "alibaba-cloud-api-to-typescript.AlibabaCloudAPIToTypescript",
        "title": "Alibaba Cloud API To Typescript"
      }
    ],
    "configuration": {
      "type": "object",
      "title": "Alibaba Cloud API To Typescript Configuration",
      "properties": {
        "alibaba-cloud-api-to-typescript.scope.produce": {
          "type": "string",
          "default": "",
          "description": "获取对应产品下的 OpenAPI 数据，同时需要添加下方版本(Version)字段"
        },
        // ...
      }
    }
  },

配置项添加完成后，要在项目中获取当前配置的值时，使用vscode.workspace.getConfiguration获取配置的值，如下：

const config = vscode.workspace.getConfiguration('alibaba-cloud-api-to-typescript');
const product = config.get<string>('scope.produce'); // 获取配置的值

二、打包

插件开发完成后我们需要打包我们的项目，打包的话需要用到VSCode官方的vsce命令行工具，首先安装vsce，可查阅vsce官方文档：

npm install -g @vscode/vsce

安装完后，在项目中运行

vsce package

打包项目为.visx文件

三、发布

插件发布也是使用vsve命令行工具。

3.1 创建个人访问令牌

首先在Azure DevOps上获取个人访问令牌

image.png

image.png

3.2 创建publisher

publisher是发布到vscode插件市场的发布者，需要在package.json中配置publisher字段，才能发布。 在 Manage Publishers & Extensions中创建publisher，将创建好的publisher填写到package.json中。

注意：创建publisher和创建个人访问令牌需要是同一个微软账号

创建完成后在终端运行

vsce login <publisher>

然后输入个人访问令牌，确认后会出现类似以下信息表明正常

The Personal Access Token verification succeeded for the publisher '你设置的publisher'

3.3 发布插件

vsce publish

3.4 使用

发布后在VSCode左侧栏拓展中搜索Alibaba Cloud API To Typescript，然后安装使用。 test-1.gif

结束语

本文主要是编写一个VSCode插件的过程，插件内部实现逻辑（怎么将JSONSchema转换成TS代码）并没有在文中赘述，感兴趣的朋友可以看源码一起学习。

参考资料

阿里云API文档

VSCode Extension API

VSCode Publishing Extensions

avatar
文章
阅读
粉丝