From 3ded0d3ac7b2985bd5cac72c4b12585b67a3171e Mon Sep 17 00:00:00 2001 From: SylvieChen <75071455+yini-chen@users.noreply.github.com> Date: Thu, 16 May 2024 20:04:50 +0800 Subject: [PATCH] feat: Enhancement of code document. (#57) --- CHANGELOG.md | 5 +++ README.md | 6 +++ README.zh_CN.md | 6 +++ src/Service.ts | 12 ++++++ src/extension.ts | 3 ++ src/provider/hoverProvider.ts | 74 +++++++++++++++++++++++++++++++++++ 6 files changed, 106 insertions(+) create mode 100644 src/provider/hoverProvider.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index ed4076c..8d00c61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Release Notes +## 0.0.10(2024-05-16) + +- SDK code documentation has been enhanced with the Code Sample link. +- Fixed some UI issues. + ## 0.0.9(2024-04-22) - The UI was optimized and a deprecated tag was added to indicate that the API is not recommended. diff --git a/README.md b/README.md index 75f3277..53306f2 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,12 @@ Or use the keyboard shortcuts `ctrl+cmd+l` to search the API and select Insert s ![code snippets](https://img.alicdn.com/imgextra/i3/O1CN01dmGwmX1ZyVHozyKx4_!!6000000003263-1-tps-842-468.gif) +### Document enhancement + +When writing SDK code, you can get more code sample references by viewing the OpenAPI description information and additional related sample links through the code documentation. + +![Document enhancement](https://img.alicdn.com/imgextra/i3/O1CN01Yj1PrE1qwzTj3cFn8_!!6000000005561-0-tps-1562-518.jpg) + ## Feedback - Submit bug reports and feature requests on [our Github repository](https://github.com/aliyun/alibabacloud-api-vscode-toolkit/issues). diff --git a/README.zh_CN.md b/README.zh_CN.md index a57a8cc..9b1b08c 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -79,6 +79,12 @@ Default Language [zh]: zh ![code snippets](https://img.alicdn.com/imgextra/i3/O1CN01dmGwmX1ZyVHozyKx4_!!6000000003263-1-tps-842-468.gif) +### 文档增强 + +你能够在编写 SDK 代码时，通过代码文档看到 OpenAPI 的描述信息以及更多相关示例链接，来获得更多代码示例参考。 + +![Document enhancement](https://img.alicdn.com/imgextra/i3/O1CN01Yj1PrE1qwzTj3cFn8_!!6000000005561-0-tps-1562-518.jpg) + ## 反馈 - 欢迎在我们的 [Github repository](https://github.com/aliyun/alibabacloud-api-vscode-toolkit/issues) 上提交你的问题和建议。 diff --git a/src/Service.ts b/src/Service.ts index 8927391..e2c8b73 100644 --- a/src/Service.ts +++ b/src/Service.ts @@ -141,6 +141,18 @@ export class AlicloudAPIService { return {}; } + /** + * @description 根据 API 查询是否有 CodeSample + */ + async requestSamplesByAPI(product: string, version: string, api: string) { + const resStr = await fetch( + `https://api.aliyun.com/api/samples/product/${product}/version/${version}/api/${api}`, + {}, + ).then((res) => res.text()); + const res = JSON.parse(resStr); + return res?.data || []; + } + async requestEndpoints(product: string) { const resStr = await fetch( `https://api.aliyun.com/meta/v1/products/${product}/endpoints.json?language=zh-CN`, diff --git a/src/extension.ts b/src/extension.ts index 844fbfb..7ebd893 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -14,6 +14,7 @@ import { AlicloudApiMetaGeneratePlugin } from "./plugins/generate"; import { getProductRequestInstance } from "./productExplorer"; import autoCompletion from "./provider/autoCompletion"; import autofix from "./provider/autofix"; +import hoverInfo from "./provider/hoverProvider"; export async function activate(context: vscode.ExtensionContext) { // if (!vscode.workspace.rootPath) { @@ -81,6 +82,8 @@ export async function activate(context: vscode.ExtensionContext) { autoCompletion(context); // 自动修复 autofix(context); + // hover提示 + hoverInfo(context); } } catch (e) { vscode.window.showErrorMessage(e.message); diff --git a/src/provider/hoverProvider.ts b/src/provider/hoverProvider.ts new file mode 100644 index 0000000..7a7ca91 --- /dev/null +++ b/src/provider/hoverProvider.ts @@ -0,0 +1,74 @@ +/** + * @author: yini-chen + * @description: hover provider + */ + +import * as vscode from "vscode"; +import { fileSel, getSpecInfoFromName } from "../utils"; +import { AlicloudAPIService, alicloudAPIMessageService } from "../Service"; +import { AlicloudApiCommands } from "../commands"; +import { getProductRequestInstance } from "../productExplorer"; + +const getKeyWord = (word: string) => { + if (/^[A-Za-z].*Request$/.test(word)) { + return word.replace("Request", ""); + } + return word; +}; + +const getProductsKeywords = (productCode: string, versions: Array): Array => { + const keywords = versions?.map((version) => { + const newVersion = version?.split("-")?.join(""); + return `${productCode}${newVersion}`.toLocaleLowerCase(); + }); + const pythonKeywords = keywords?.map((key) => { + return `${key}client`; + }); + keywords.push(productCode.toLocaleLowerCase()); + return [...keywords, ...pythonKeywords]; +}; + +class HoverProvider { + async provideHover(document: vscode.TextDocument, position: vscode.Position) { + const service = alicloudAPIMessageService; + const apis = service.pontManager.localPontSpecs + .map((pontSpec) => { + return AlicloudApiCommands.getPickItems(pontSpec); + }) + .reduce((pre, next) => pre.concat(next), []); + + const wordRange = document.getWordRangeAtPosition(position); + const word = document.getText(wordRange); + const keyWord = getKeyWord(word); + + const hoverdAPI = apis?.find((item) => item?.label?.toLocaleLowerCase() === keyWord?.toLocaleLowerCase()); + const productInstance = await getProductRequestInstance(); + const hoverdProduct = productInstance?.products?.find((item) => + getProductsKeywords(item.code, item.versions)?.includes(keyWord?.toLocaleLowerCase()), + ); + // 匹配关键字为 API 名称 + if (hoverdAPI) { + const apiName = hoverdAPI?.label; + const { product, version } = getSpecInfoFromName(hoverdAPI?.info?.split("/")[0]); + const service = new AlicloudAPIService(); + const samples = await service.requestSamplesByAPI(product, version, keyWord); + return new vscode.Hover([ + samples?.length + ? `💡 [查看更多「${apiName}」相关代码示例](https://api.aliyun.com/api/${product}/${version}/${apiName}?tab=CodeSample)` + : `💡 [查看更多「${product}」的相关代码示例](https://api.aliyun.com/api-tools/demo/${product})`, + hoverdAPI?.summary || "", + ]); + } + // 匹配关键字为产品名称 + if (hoverdProduct) { + return new vscode.Hover([ + `💡 [查看更多「${hoverdProduct?.name || hoverdProduct?.code}」的相关代码示例](https://api.aliyun.com/api-tools/demo/${hoverdProduct?.code})`, + hoverdProduct?.description || hoverdProduct?.name, + ]); + } + } +} + +export default function (context: vscode.ExtensionContext) { + context.subscriptions.push(vscode.languages.registerHoverProvider(fileSel, new HoverProvider())); +}