feat: Enhancement of code document. (#57)

Author: yini-chen

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.

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).

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) 上提交你的问题和建议。

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`,

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);

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<string>): Array<string> => {
+  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()));
+}