VSCode extension: add openapi3 preview

.chronus/changes/vscode-openapi-preview-2025-1-14-15-22-4.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - typespec-vscode
+---
+
+add openapi3 preview

.prettierignore

@@ -61,5 +61,8 @@ packages/http-client-csharp/generator/TestProjects/**/tspCodeModel.json
 packages/http-client-java/generator/http-client-generator-test/src/main/**/*.json
 packages/http-client-java/generator/http-client-generator-clientcore-test/src/main/**/*.json
 
+# swagger-ui-dist lib files
+packages/typespec-vscode/swagger-ui/swagger-ui*
+
 .gitattributes
 CODEOWNERS

eslint.config.js

@@ -148,6 +148,7 @@ export default tsEslint.config(
       "packages/compiler/templates/**/*", // Ignore the templates which might have invalid code and not follow exactly our rules.
       "**/venv/**/*", // Ignore python virtual env
       "**/.vscode-test-web/**/*", // Ignore VSCode test web project
+      "packages/typespec-vscode/swagger-ui/swagger-ui*", // Ignore swagger-ui-dist files
       // TODO: enable
       "**/.scripts/**/*",
       "eng/tsp-core/scripts/**/*",

packages/typespec-vscode/.vscodeignore

@@ -9,6 +9,7 @@
 !dist/**/*.js
 !dist/**/*.cjs
 !dist/**/*.js.map
+!dist/**/*.css
 !dist/**/language-configuration.json
 dist/test/
 
@@ -18,3 +19,4 @@ dist/test/
 !LICENSE
 !icons/
 !snippets.json
+!swagger-ui/

packages/typespec-vscode/package.json

@@ -116,19 +116,29 @@
       "explorer/context": [
         {
           "command": "typespec.importFromOpenApi3",
-          "group": "typespec@2"
+          "group": "typespec@3"
         },
         {
           "command": "typespec.generateCode",
           "when": "explorerResourceIsFolder || resourceLangId == typespec",
           "group": "typespec@1"
+        },
+        {
+          "command": "typespec.showOpenApi3",
+          "when": "resourceLangId == typespec",
+          "group": "typespec@2"
         }
       ],
       "editor/context": [
         {
           "command": "typespec.generateCode",
           "when": "resourceLangId == typespec",
           "group": "typespec@1"
+        },
+        {
+          "command": "typespec.showOpenApi3",
+          "when": "resourceLangId == typespec",
+          "group": "typespec@2"
         }
       ]
     },
@@ -180,6 +190,11 @@
         "command": "typespec.importFromOpenApi3",
         "title": "Import TypeSpec from OpenApi3",
         "category": "TypeSpec"
+      },
+      {
+        "command": "typespec.showOpenApi3",
+        "title": "Show OpenAPI3 Documentation",
+        "category": "TypeSpec"
       }
     ],
     "semanticTokenScopes": [
@@ -225,14 +240,15 @@
   },
   "scripts": {
     "clean": "rimraf ./dist ./temp",
-    "build": "npm run compile && npm run copy-tmlanguage && npm run generate-language-configuration && npm run generate-third-party-notices && npm run package-vsix",
+    "build": "npm run compile && npm run copy-tmlanguage && npm run copy-swagger-ui-dist && npm run generate-language-configuration && npm run generate-third-party-notices && npm run package-vsix",
     "compile": "rollup --config rollup.config.ts --configPlugin typescript --failAfterWarnings 2>&1",
     "watch": "rollup --config rollup.config.ts --configPlugin typescript --watch",
     "dogfood": "node scripts/dogfood.js",
     "copy-tmlanguage": "node scripts/copy-tmlanguage.js",
+    "copy-swagger-ui-dist": "node scripts/copy-swagger-ui-dist.js",
     "generate-language-configuration": "node scripts/generate-language-configuration.js",
     "generate-third-party-notices": "typespec-build-tool generate-third-party-notices",
-    "package-vsix": "vsce package",
+    "package-vsix": "vsce package --no-dependencies",
     "deploy": "vsce publish",
     "open-in-browser": "vscode-test-web --extensionDevelopmentPath=. .",
     "test:e2e": "pnpm test:web",
@@ -244,8 +260,8 @@
     "@rollup/plugin-typescript": "~12.1.0",
     "@types/mocha": "^10.0.9",
     "@types/node": "~22.10.10",
-    "@types/vscode": "~1.96.0",
     "@types/semver": "^7.5.8",
+    "@types/vscode": "~1.96.0",
     "@typespec/compiler": "workspace:~",
     "@typespec/internal-build-utils": "workspace:~",
     "@vitest/coverage-v8": "^3.0.4",
@@ -261,5 +277,8 @@
     "vitest": "^3.0.5",
     "vscode-languageclient": "~9.0.1",
     "yaml": "~2.7.0"
+  },
+  "dependencies": {
+    "swagger-ui-dist": "^5.18.2"
   }
 }

packages/typespec-vscode/scripts/copy-swagger-ui-dist.js

@@ -0,0 +1,14 @@
+import { copyFile } from "fs/promises";
+
+await copyFile(
+  "node_modules/swagger-ui-dist/swagger-ui.css",
+  "../typespec-vscode/dist/swagger-ui.css",
+);
+await copyFile(
+  "node_modules/swagger-ui-dist/swagger-ui-bundle.js",
+  "../typespec-vscode/dist/swagger-ui-bundle.js",
+);
+await copyFile(
+  "node_modules/swagger-ui-dist/swagger-ui-standalone-preset.js",
+  "../typespec-vscode/dist/swagger-ui-standalone-preset.js",
+);

packages/typespec-vscode/src/extension.ts

@@ -18,6 +18,7 @@ import { createTypeSpecProject } from "./vscode-cmd/create-tsp-project.js";
 import { emitCode } from "./vscode-cmd/emit-code/emit-code.js";
 import { importFromOpenApi3 } from "./vscode-cmd/import-from-openapi3.js";
 import { installCompilerGlobally } from "./vscode-cmd/install-tsp-compiler.js";
+import { clearOpenApi3PreviewTempFolders, showOpenApi3 } from "./vscode-cmd/openapi3-preview.js";
 
 let client: TspLanguageClient | undefined;
 /**
@@ -114,6 +115,12 @@ export async function activate(context: ExtensionContext) {
     }),
   );
 
+  context.subscriptions.push(
+    commands.registerCommand(CommandName.ShowOpenApi3, async (uri: vscode.Uri) => {
+      await showOpenApi3(uri, context, client!);
+    }),
+  );
+
   context.subscriptions.push(
     vscode.workspace.onDidChangeConfiguration(async (e: vscode.ConfigurationChangeEvent) => {
       if (e.affectsConfiguration(SettingName.TspServerPath)) {
@@ -171,6 +178,7 @@ export async function activate(context: ExtensionContext) {
 
 export async function deactivate() {
   await client?.stop();
+  await clearOpenApi3PreviewTempFolders();
 }
 
 async function recreateLSPClient(context: ExtensionContext) {

packages/typespec-vscode/src/tsp-language-client.ts

@@ -224,4 +224,24 @@ export class TspLanguageClient {
     const lc = new LanguageClient(id, name, { run: exe, debug: exe }, options);
     return new TspLanguageClient(lc, exe);
   }
+
+  async compileOpenApi3(
+    mainTspFile: string,
+    srcFolder: string,
+    outputFolder: string,
+  ): Promise<ExecOutput | undefined> {
+    const result = await this.runCliCommand(
+      [
+        "compile",
+        mainTspFile,
+        "--emit=@typespec/openapi3",
+        "--option",
+        "@typespec/openapi3.file-type=json",
+        "--option",
+        `@typespec/openapi3.emitter-output-dir=${outputFolder}`,
+      ],
+      srcFolder,
+    );
+    return result;
+  }
 }

packages/typespec-vscode/src/types.ts

@@ -11,6 +11,7 @@ export const enum CommandName {
   OpenUrl = "typespec.openUrl",
   GenerateCode = "typespec.generateCode",
   ImportFromOpenApi3 = "typespec.importFromOpenApi3",
+  ShowOpenApi3 = "typespec.showOpenApi3",
 }
 
 export interface InstallGlobalCliCommandArgs {

packages/typespec-vscode/src/utils.ts

@@ -1,6 +1,7 @@
 import type { ModuleResolutionResult, NodePackage, ResolveModuleHost } from "@typespec/compiler";
 import { spawn, SpawnOptions } from "child_process";
-import { readFile, realpath, stat } from "fs/promises";
+import { mkdir, readFile, realpath, stat } from "fs/promises";
+import { tmpdir } from "os";
 import { dirname } from "path";
 import { CancellationToken } from "vscode";
 import { Executable } from "vscode-languageclient/node.js";
@@ -27,6 +28,24 @@ export async function isDirectory(path: string) {
   }
 }
 
+export async function createTempDir(): Promise<string | undefined> {
+  try {
+    const tempDir = tmpdir();
+    const realTempDir = await realpath(tempDir);
+    const uid = createGuid();
+    const subDir = joinPaths(realTempDir, uid);
+    await mkdir(subDir);
+    return subDir;
+  } catch (e) {
+    logger.error("Failed to create temp folder", [e]);
+    return undefined;
+  }
+}
+
+function createGuid() {
+  return crypto.randomUUID();
+}
+
 export function isWhitespaceStringOrUndefined(str: string | undefined): boolean {
   return str === undefined || str.trim() === "";
 }
@@ -389,3 +408,33 @@ export async function loadPackageJsonFile(
   if (!packageJson) return undefined;
   return packageJson as NodePackage;
 }
+
+export async function parseJsonFromFile(filePath: string): Promise<string | undefined> {
+  try {
+    const fileContent = await readFile(filePath, "utf-8");
+    const content = JSON.parse(fileContent);
+    return content;
+  } catch (e) {
+    logger.error(`Failed to load JSON file: ${filePath}`, [e]);
+    return;
+  }
+}
+
+/**
+ * Throttle the function to be called at most once in every blockInMs milliseconds. This utility
+ * is useful when your event handler will trigger the same event multiple times in a short period.
+ *
+ * @param fn Underlying function to be throttled
+ * @param blockInMs Block time in milliseconds
+ * @returns a throttled function
+ */
+export function throttle<T extends (...args: any[]) => any>(fn: T, blockInMs: number): T {
+  let time: number | undefined;
+  return function (this: any, ...args: Parameters<T>) {
+    const now = Date.now();
+    if (time === undefined || now - time >= blockInMs) {
+      time = now;
+      fn.apply(this, args);
+    }
+  } as T;
+}