VSCode extension: add openapi3 preview #6015

archerzz · 2025-02-14T07:31:38Z

add command to preview the main.tsp of the selected tsp file
- each main tsp can have its own preview panel
- preview panel will auto-refresh when a tsp file is changed
if multiple swagger definition is generated, command will prompt users to select one
- the selection will be kept until the preview panel is closed
swagger definition is generated to a temp folder
- temp folders will be cleared on deactivation
a minimal version of tsp 0.65.0 is required to simplify implementation
due to vsce package not supporting pnpm, I have to copy swagger-ui-dist lib files into our source folder. So, add those files into ignore list of lint and format.

resolve #4858

# Conflicts: # packages/typespec-vscode/package.json # packages/typespec-vscode/src/extension.ts # packages/typespec-vscode/src/types.ts # pnpm-lock.yaml

# Conflicts: # pnpm-lock.yaml

archerzz · 2025-02-14T07:33:29Z

I have to copy swagger-ui-dist libs instead of importing them as dependencies, because pnpm is actually not supported in vsce package.

azure-sdk · 2025-02-14T07:34:10Z

All changed packages have been documented.

✅ typespec-vscode

Show changes

`typespec-vscode` - feature ✏️

add openapi3 preview

azure-sdk · 2025-02-14T07:48:34Z

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

archerzz · 2025-02-14T08:21:55Z

https://github.com/arjun-g/vs-swagger-viewer is not suitable as a dependent extension for previewing swagger, because it only exposes a load method, which doesn't fulfill our requirement:

We cannot get the panel instance, which means:
- we don't know when the panel is closed
- we cannot manually switch panel from background to front ground
It maintains an HTTP server internally, which means more runtime footprint

…ndling logic

archerzz · 2025-02-21T02:51:40Z

List of changes since last review:

update ordering of commands and menu items according to comments
refactor parseOpenApi3File to make it generic
- add a new parseOpenApi3File in the openapi3-preview.ts which handles UI specific logic
add selected file in the error logs if it's available

packages/typespec-vscode/package.json

packages/typespec-vscode/src/vscode-cmd/openapi3-preview.ts

archerzz · 2025-02-26T08:08:35Z

List of changes since last review:

move swagger-ui-dist from dependencies to devDependencies
use rollup to copy files of swagger-ui-dist
do not show pop-up message when user cancels file selection
re-use TraverseMainTspFileInWorkspace() in typespec-utils.ts

packages/typespec-vscode/package.json

timotheeguerin · 2025-02-27T17:22:21Z

packages/typespec-vscode/src/utils.ts

@@ -27,6 +28,24 @@ export async function isDirectory(path: string) {
  }
 }

+export async function createTempDir(): Promise<string | undefined> {


node has mkdtemp which does that too

timotheeguerin · 2025-02-27T17:24:21Z

packages/typespec-vscode/src/vscode-cmd/openapi3-preview.ts

+    return;
+  }
+
+  const mainTspFile = selectedFile.endsWith("main.tsp") ? selectedFile : await getMainTspFile();


this is the same issue as #6062, if the user asked for a preview of a file it should respect that and not try to fetch a main.tsp

when I discussed this feature with Rodge, we thought we should show the full open api 3 spec v.s. just the selected spec. Sometimes, showing the selected spec may be meaningless. For example, client.tsp is for client codes, so it should not have impact on the Open API 3 output which is for service API.

@RodgeFu Your thought?

Yeah but it's not up to you to decide that for the user. Typespec compile takes any file as entry point it just default to a file called main.tsp when you target a directory compile .

Client.tsp is not the only use case. At the very least there should be a choice the user can make.

I think this is about how the files in project can be compiled properly. I believe in most case, starting compilation from "main.tsp" is still the right way to go and simply using the file user selected as entrypoint is likely not to compile the project as expected. So I think we should keep the "main.tsp" as the default behavior while providing some way for people to have the choice when needed.
Some options I can think about:

provide a settings for user to set entrypoint file when needed

adding a quickpick step for people to select main.tsp (default) or the selected file when user clicks preview

Actually the first one feels like something should be in tspconfig.yaml instead of vscode. @timotheeguerin , do we have any plan for it there?
open to any better ideas.

right now there is if there is a exports or tspMain(deprecated) in package.json but nothing to have sub project per package. Having many project per package is still quite a common use case(whole of the specs repos)

Maybe we should investigate also providing an entrypoint from the config but the way it works today is the other way around it resolve a config for an entrypoint which many can share

timotheeguerin · 2025-02-27T17:25:58Z

packages/typespec-vscode/src/vscode-cmd/openapi3-preview.ts

+  return tmpFolder;
+}
+
+export async function clearOpenApi3PreviewTempFolders() {


where is this used?

It's in the deactivate() of the extension: https://github.com/microsoft/typespec/pull/6015/files#diff-b4f57e7b0dc2be510cb4bedc0265dbc5dc1f8805e1a81497df90ee5c09049bc3R181 to try best to not leave trash files

timotheeguerin · 2025-02-27T17:26:16Z

packages/typespec-vscode/src/vscode-cmd/openapi3-preview.ts

+}
+
+async function getOutputFolder(mainTspFile: string): Promise<string | undefined> {
+  let tmpFolder = openApi3TempFolders.get(mainTspFile);


when does caching become useful here?

When a tsp file is changed, the file watcher will re-generate open api 3 output and reload the preview panel. At that time, if the corresponding temp folder is already created, it will re-use that folder.

When the preview panel is closed and opened again, the same logic will be triggered.

Do you clear the dir in between, if the user goes change the name of services or version it could create ghost files otherwise

Mingzhe Huang (from Dev Box) added 14 commits January 22, 2025 11:00

init check-in

ac13a8e

do not use tmp folder

8e9c36b

open preview panel only after swagger file is generated

5f4bba3

Merge branch 'main' into vscode/openapi-preview

64e14d8

# Conflicts: # packages/typespec-vscode/package.json # packages/typespec-vscode/src/extension.ts # packages/typespec-vscode/src/types.ts # pnpm-lock.yaml

improve multiple swagger file selection ui

63492f3

use temp folder to host preview output

556e9db

Merge branch 'main' into vscode/openapi-preview

9166069

# Conflicts: # pnpm-lock.yaml

fix pnpm not supprted in vsce package

f057599

fix command title

c202688

Check minimal version of compiler

84dd3f8

Merge branch 'main' into vscode/openapi-preview

baae442

# Conflicts: # pnpm-lock.yaml

improve file selection error

e87fc7c

improve error handling

b5a1f69

add chronus change log

e224bde

archerzz requested review from RodgeFu, bterlson, markcowl, allenjzhang, timotheeguerin, chrisradek and AlitzelMendez as code owners February 14, 2025 07:31

Merge branch 'main' into vscode/openapi-preview

9185597

RodgeFu added the ide Issues for VS, VSCode, Monaco, etc. label Feb 14, 2025

Mingzhe Huang (from Dev Box) added 2 commits February 14, 2025 16:10

fix lint and format errors

ae60f8c

roll back changes in license notice

fcd4a5c

archerzz requested a review from witemple-msft as a code owner February 14, 2025 08:10

Mingzhe Huang (from Dev Box) added 3 commits February 21, 2025 10:46

update ordering of commands and menu items

69bf3ce

rename parseOpenApi3File to parseJsonFromFile and change error ha…

ab1889e

…ndling logic

add selected file in the error log if it's available

ef3981c

archerzz requested review from iscai-msft, tadelesh, srnagar, weidongxu-microsoft, haolingdong-msft, XiaofeiCao, m-nash, JoshLove-msft and jorgerangel-msft as code owners February 21, 2025 02:46

Merge branch 'main' into vscode/openapi-preview

ed00127

archerzz added 2 commits February 24, 2025 10:24

Merge branch 'main' into vscode/openapi-preview

3bce4db

Merge branch 'main' into vscode/openapi-preview

8f74429

RodgeFu reviewed Feb 26, 2025

View reviewed changes

packages/typespec-vscode/package.json Outdated Show resolved Hide resolved

RodgeFu reviewed Feb 26, 2025

View reviewed changes

packages/typespec-vscode/src/vscode-cmd/openapi3-preview.ts Outdated Show resolved Hide resolved

RodgeFu reviewed Feb 26, 2025

View reviewed changes

packages/typespec-vscode/src/vscode-cmd/openapi3-preview.ts Outdated Show resolved Hide resolved

RodgeFu requested a review from timotheeguerin February 26, 2025 04:07

archerzz and others added 5 commits February 26, 2025 15:04

Merge branch 'main' into vscode/openapi-preview

f403f70

re-use TraverseMainTspFileInWorkspace() in typespec-utils.ts

0c85f2f

do not show pop-up message when user cancels file selection

c3e39de

move swagger-ui-dist from dependencies to devDependencies

5d520df

use rollup to copy swaigger-ui-dist files

48dbbe1

Merge branch 'main' into vscode/openapi-preview

ee3a135

RodgeFu reviewed Feb 27, 2025

View reviewed changes

packages/typespec-vscode/package.json Show resolved Hide resolved

timotheeguerin changed the title ~~feat(vscode): add openapi3 preview~~ VSCode extension: add openapi3 preview Feb 27, 2025

timotheeguerin reviewed Feb 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

VSCode extension: add openapi3 preview #6015

VSCode extension: add openapi3 preview #6015

archerzz commented Feb 14, 2025 •

edited

Loading

archerzz commented Feb 14, 2025

azure-sdk commented Feb 14, 2025 •

edited

Loading

`typespec-vscode` - feature ✏️

azure-sdk commented Feb 14, 2025 •

edited

Loading

archerzz commented Feb 14, 2025

archerzz commented Feb 21, 2025

archerzz commented Feb 26, 2025

timotheeguerin Feb 27, 2025

timotheeguerin Feb 27, 2025

archerzz Feb 28, 2025

timotheeguerin Feb 28, 2025

RodgeFu Feb 28, 2025

timotheeguerin Feb 28, 2025

timotheeguerin Feb 27, 2025

archerzz Feb 28, 2025

timotheeguerin Feb 27, 2025

archerzz Feb 28, 2025

timotheeguerin Feb 28, 2025

VSCode extension: add openapi3 preview #6015

Are you sure you want to change the base?

VSCode extension: add openapi3 preview #6015

Conversation

archerzz commented Feb 14, 2025 • edited Loading

archerzz commented Feb 14, 2025

azure-sdk commented Feb 14, 2025 • edited Loading

typespec-vscode - feature ✏️

azure-sdk commented Feb 14, 2025 • edited Loading

archerzz commented Feb 14, 2025

archerzz commented Feb 21, 2025

archerzz commented Feb 26, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

archerzz commented Feb 14, 2025 •

edited

Loading

azure-sdk commented Feb 14, 2025 •

edited

Loading

`typespec-vscode` - feature ✏️

azure-sdk commented Feb 14, 2025 •

edited

Loading