46 lines
1.3 KiB
Markdown
46 lines
1.3 KiB
Markdown
# knife4j-swagger-vue3
|
|
|
|
基于 Vue3 重构的 Knife4j 风格 Swagger/OpenAPI 文档 UI。
|
|
|
|
## 目标
|
|
|
|
- 解析逻辑严格遵守 Swagger 2.0 / OpenAPI 3.x 标准字段。
|
|
- UI 布局、颜色、表格和接口树风格对齐 Knife4j。
|
|
- 支持深层 `$ref`、`allOf`、`oneOf`、`anyOf`、数组对象和响应示例。
|
|
- 不依赖旧 Knife4j 前端解析器，避免响应参数和响应示例显示不稳定。
|
|
|
|
## 目录
|
|
|
|
| 路径 | 说明 |
|
|
| --- | --- |
|
|
| `packages/openapi-parser` | Swagger/OpenAPI 标准解析器 |
|
|
| `packages/knife4j-vue3-ui` | Vue3 Knife4j 风格 UI 组件 |
|
|
| `apps/playground` | 本地调试入口，默认代理到 `127.0.0.1:48085` |
|
|
|
|
## 使用
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
默认打开 `http://127.0.0.1:5188`，服务列表会读取：
|
|
|
|
- `/api-json`
|
|
- `/api/admin-json`
|
|
- `/api/qqbot-json`
|
|
- `/api/wordpress-json`
|
|
- `/api/basic-json`
|
|
|
|
## 标准字段约定
|
|
|
|
响应示例按以下优先级读取：
|
|
|
|
1. `responses[code].content[mediaType].example`
|
|
2. `responses[code].content[mediaType].examples[*].value`
|
|
3. `responses[code].schema.example`
|
|
4. `components.schemas[*].example` / `definitions[*].example`
|
|
5. 根据 schema 的 `properties/items/type/default/example` 生成兜底示例
|
|
|
|
响应参数按标准 schema 展开，不读取 Knife4j 私有字段。
|