czh-api VSCode 插件

作者：Czh 本插件是为 czh-api 工具量身打造的 VSCode 辅助工具，旨在将 API 文档与代码生成无缝集成到您的开发环境中，提供高效、便捷的 API 浏览和管理体验。

✨ 核心特性

API 树状视图: 在 VSCode 侧边栏直观地展示所有 API。
智能分组:
- 自动分组: 如果项目的 Swagger 服务支持 swagger-config，插件将自动获取分组信息，并以 分组 -> 模块 -> 接口 的三级结构进行展示。
- 优雅回退: 如果无法获取分组信息，插件会自动回退，以 模块 -> 接口 的二级结构展示，确保在不同环境下的可用性。
- FastAPI 兼容: 支持 FastAPI / OpenAPI 3.1 文档（如 /openapi.json），并自动选择更合适的加载策略。
丰富的视图操作:
- 初始化项目: 一键执行 npx czh-api init，快速生成配置文件。
- 生成 API 代码: 一键执行 npx czh-api build，并将生成的文件夹在资源管理器中高亮显示。
- 实时搜索: 在视图内对模块、路径、描述等信息进行模糊搜索，快速定位目标接口。
- 刷新视图: 手动与远程 API 文档同步，更新树状视图。
强大的接口详情:
- 独立视图: 点击任意接口，将在新的 Webview 标签页中展示其详细信息。
- 内置 Swagger UI: 集成 Swagger UI，支持在 VSCode 中直接查看和测试接口。
- 请求代理: 内置请求代理，解决跨域问题，可直接在插件内发起 API 请求。
- 结构化展示: 清晰地列出请求参数、请求体、响应状态、响应参数及响应示例。
- 层级化参数: 对复杂的请求体和响应参数（如嵌套对象、数组）提供带缩进和折叠功能的层级视图，方便查阅。
- 浏览器联动: 在接口详情页和视图标题栏都提供了"在浏览器中打开"的按钮，可一键跳转到 Knife4j / Swagger / FastAPI Docs（/docs）页面。
- 引用解析增强: 对接口详情中的本地 $ref（如 #/components/schemas/...）做了预解析，降低解析失败概率。
- 参数布局优化: 字段名称或类型声明较长时支持自适应宽度，减少异常换行。
自定义请求头: 支持配置项目级自定义请求头（如 Token），配置保存在 czh-api.headers.json 文件中，支持启用/禁用单个请求头。
主题支持: 支持暗色/亮色主题切换，可在 VSCode 设置中配置 czh-api.theme。
自定义图标: 拥有一个精心设计的独立插件图标。

🚀 使用指南

1. 安装插件

您可以将本项目打包成 .vsix 文件。
打开 VSCode，在插件市场侧边栏中，点击右上角的 ... 菜单，选择 "从 VSIX 安装..."，然后选中打包好的文件。

2. 初始化项目

在 VSCode 中打开您的项目文件夹。
在左侧活动栏中点击本插件的图标，打开 API 视图。
如果项目中缺少 czh-api.config.json 文件，视图上方会显示一个 "初始化项目" ( + ) 图标，点击它。
插件会自动在项目根目录为您生成 czh-api.config.json 文件。

3. 配置与使用

打开 czh-api.config.json 文件，将其中的 url 字段修改为您的项目对应的 Swagger/OpenAPI 文档地址 (例如：http://localhost:8080/v3/api-docs 或 http://localhost:8000/openapi.json)。
保存文件后，API 视图将自动刷新并加载所有接口。
现在，您可以开始浏览、搜索和查看您的 API 了。

📂 命令列表

命令	标题	功能描述
`czh-api-vscode-plugin.init`	CZH API: 初始化项目 (init)	在项目根目录创建 `czh-api.config.json` 文件。
`czh-api-vscode-plugin.build`	CZH API: 生成 API (build)	执行 `npx czh-api build` 命令来生成 API 客户端代码。
`czh-api-vscode-plugin.refresh`	CZH API: 刷新	重新从远程地址获取 API 文档并刷新视图。
`czh-api-vscode-plugin.search`	CZH API: 搜索	在 API 树状视图中进行关键字模糊搜索。
`czh-api-vscode-plugin.openSwagger`	CZH API: 在浏览器中打开文档	在浏览器中打开项目的整体 API 文档页面（如 `doc.html` 或 FastAPI 的 `docs`）。

⚙️ 配置项

在 VSCode 设置中搜索 czh-api 可配置以下选项：

配置项	类型	默认值	说明
`czh-api.theme`	`string`	`dark`	Swagger UI 显示主题，可选 `dark` 或 `light`

📁 配置文件说明

文件名	说明
`czh-api.config.json`	主配置文件，包含 API 文档地址 (`url`) 和输出目录 (`outputDir`)；`url` 支持 `http(s)`、`file://`、本地相对/绝对路径
`czh-api.headers.json`	自定义请求头配置文件（可选），用于配置 Token 等认证信息

czh-api.config.json 示例

{
  "url": "https://api.example.com/openapi.json",
  "outputDir": "./src/api"
}

{
  "url": "http://localhost:8080/v3/api-docs",
  "outputDir": "./src/api"
}

czh-api.headers.json 示例

[
  {
    "key": "Authorization",
    "value": "Bearer your-token-here",
    "enabled": true
  },
  {
    "key": "X-Custom-Header",
    "value": "custom-value",
    "enabled": false
  }
]

📦 如何打包

要将此项目打包成 .vsix 文件以供分发和安装，请执行以下步骤：

安装 VSCE (一次性):
```
npm install -g @vscode/vsce
```
进入项目根目录:
```
cd path/to/czh-api-vscode-plugin
```
执行打包命令:
```
vsce package
```

打包成功后，会在项目根目录下生成 czh-api-vscode-plugin-x.x.x.vsix 文件。

发布到vscode插件市场 vsce login <你的发布者名称> vsce publish 或者指定版本号发布： vsce publish 1.0.0

❓ 常见问题

1. Try it out 报错 `Failed to fetch`

请先确认 czh-api.config.json 里的 url 可正常访问。
如接口需要鉴权，请在 czh-api.headers.json 中配置请求头（例如 Authorization）。
修改插件后请先执行 npm run compile，然后在 VSCode 执行 Developer: Reload Window。

2. 详情页出现 `$ref` 解析错误

请确认原始 OpenAPI 文档中 components/schemas 定义完整。
插件已对本地 $ref 做预解析；若仍异常，请将对应接口片段和 schema 片段提交 issue 便于定位。

🔧 环境要求

VSCode 版本 >= 1.75.0
Node.js >= 20（打包时需要）
项目需要能访问 Swagger/OpenAPI 文档地址

📝 更新日志

查看 CHANGELOG.md 了解版本更新详情。

享受高效的 API 开发体验吧！

czh-api-vscode-plugin

ChenZH