openapi: 3.1.0
info:
title: vjmap HTTP API
version: "1.0.0"
summary: vjmap web服务 + 图形服务 HTTP 接口
description: |
本规范覆盖 `vjmap` 二次开发最常用的 ~40 个接口，按照 13 大分类组织。
- **Base URL**：`http://127.0.0.1:27660`
- **API 前缀**：`/api/v1`
- **鉴权**：JWT Token，通过请求头 `token:`（优先）或查询参数 `?token=` 传递；REST 不认 `Authorization: Bearer`（仅 MCP 路由认）
- **响应约定**：
- web服务类接口：统一 `{"code":0,"msg":"ok","data":...}`
- 图形服务直通接口（`/api/v1/map/cmd/...`）： JSON
- 字节流接口（瓦片 / PBF / PNG）：直接返回二进制
> 本规范随新后端文档项目一起分发，Swagger 页面可在线 "Try it out"。
contact:
name: vjmap dev
license:
name: Proprietary
servers:
- url: http://127.0.0.1:27660
description: 本地调试服务
- url: http://127.0.0.1:27660/api/v1
description: API 前缀路径（部分集成场景）
security:
- TokenQuery: []
- TokenHeader: []
tags:
- name: Map Management
description: 地图上传 / 打开 / 关闭 / 删除 / 元数据
- name: Tiles & Styles
description: 栅格 / 矢量瓦片、WMS、样式管理
- name: Query
description: 要素查询、坐标变换
- name: Analysis
description: 图形差分 / 对比 / 表格抽取 等高级分析
- name: Compose & Export
description: 组合拆分地图、导出 PDF / DXF / 离线包
- name: WebCAD
description: 在线 CAD 编辑（可选功能）
- name: Workspace
description: 工作区（命名空间）管理
- name: Data Storage
description: 键值数据存储
- name: Full-text Search
description: CAD 文字全文索引（Bleve）
- name: Symbols
description: 符号库（只读）
- name: System
description: 心跳 / 版本 / 运行状态 / 日志
- name: Misc Services
description: 二维码 / 字体 glyphs / 图片上传
- name: AI
description: 向量检索 / FAQ / 知识库文档
components:
securitySchemes:
TokenQuery:
type: apiKey
in: query
name: token
TokenHeader:
type: apiKey
in: header
name: token
parameters:
MapIdPath:
name: mapid
in: path
required: true
schema: { type: string }
description: 地图 ID
VersionPath:
name: version
in: path
required: true
schema: { type: string, default: v1 }
description: 版本号，默认 v1
schemas:
GatewayError:
description: web服务标准错误包
type: object
properties:
code: { type: integer, example: 7 }
msg: { type: string, example: "Token is invalid" }
data: { type: object, example: { reload: true } }
ServiceOk:
description: /service/* 系列的标准 OK 包
type: object
properties:
status: { type: string, example: "ok" }
data: { }
CmdBoolResult:
description: "/cmd/* 命令返回的 { status: true|false, ... } 结构"
type: object
properties:
status: { type: boolean }
additionalProperties: true
# ---------- Map ----------
UploadResponse:
type: object
description: |
上传结果。同内容文件已被某图使用时 mapid 为该图并带 version/geom；
图片带 maptype；失败时为 {uploadname, error}。
properties:
fileid: { type: string, example: "caf27de8a225", description: "c/t + 内容 md5 前 11 位" }
mapid: { type: string, example: "caf27de8a225" }
uploadname: { type: string, example: "my.dwg", description: 回显上传原文件名 }
version: { type: string, example: "v1" }
geom: { type: boolean }
maptype: { type: string, example: "image" }
error: { type: string }
OpenMapRequest:
type: object
required: [mapid]
description: |
打开地图请求体。
- `mapid` 必填，需与 URL path 中的 `{mapid}` 保持一致。
- `fileid` 选填：首次打开新上传的图时必填（取自 `POST /api/v1/map/uploads`
的返回值）；已存在的图可省略。
- 打开方式只看布尔 `geom`（后端缺省 false = Memory）；后端不读 `mapopenway`
（客户端枚举，官方 SDK 换算为 `geom = mapopenway !== 'Memory'`）。
- GeomRender 首次打开异步：返回 `{mapid,version,status:"working",error}`，轮询
`cmd/listmaps/{mapid}/{version}` 到 status=finish 后再打开一次。
properties:
mapid: { type: string, example: "demo_123", description: "地图 ID（与 URL path 中的 {mapid} 保持一致）" }
version: { type: string, example: "v1", description: "POST 时只读 body（query 里的 version 不读）" }
fileid: { type: string, example: "caf27de8a225", description: "上传接口返回的 fileid" }
uploadname: { type: string, example: "caf27de8a225.dwg", description: "上传接口返回的 uploadname，选填" }
geom: { type: boolean, default: false, description: "true=GeomRender（几何渲染），false=Memory（内存打开；从未以 true 打开过的图 cmd 走内存进程，不支持 condition 查询）" }
style: { type: object }
secretKey: { type: string, description: "v1 首次打开且 ≥10 位时设为该图密钥（原样存）；之后用于校验。同名请求头会覆盖它" }
accessKey: { type: string, description: "该图 accessKey（仅浏览）或实例 map_super_key" }
mapbounds: { type: string, example: "[0,0,100,100]" }
layers: { type: array, items: { type: string } }
example:
mapid: "demo_123"
fileid: "caf27de8a225"
uploadname: "caf27de8a225.dwg"
geom: true
OpenMapResponse:
type: object
additionalProperties: true
properties:
mapid: { type: string }
version: { type: string }
fileid: { type: string }
status: { type: string, description: "GeomRender 首次打开为 working；完成后为 finish" }
geom: { type: string, enum: ["true", "false"], description: 实际打开方式（字符串） }
layer: { type: string, example: "s6d04d896e", description: "当前样式图层名 = 瓦片 URL 的 {layer} 段" }
bounds: { type: string, description: "'[x1,y1,x2,y2]'" }
layers: { type: string, description: "图层数组的 JSON 字符串" }
styles: { type: string, description: "样式数组的 JSON 字符串" }
defaultlayer: { type: string }
error: { type: string }
MapVersionInfo:
type: object
properties:
version: { type: string, example: "v1" }
status: { type: string, example: "finish", description: "working / finish / error / runerror" }
geom: { type: boolean }
db: { type: string }
filename: { type: string }
uploadname: { type: string }
mtime: { type: string, example: "2026-04-10 12:00:00" }
errmsg: { type: string }
ListMapsResponse:
description: |
不带分页参数：{mapid: [MapVersionInfo]}（顶层键是动态 mapid）。
带 curPage/pageCount（均 >0）：分页信封 {count, curPage, pageCount, mapIds:[本页 mapid],
mapInfos:{mapid:[MapVersionInfo]}, allMapIds:[实例全部 mapid，不做前缀隐藏]}。
oneOf:
- type: object
additionalProperties:
type: array
items: { $ref: "#/components/schemas/MapVersionInfo" }
- type: object
properties:
count: { type: integer }
curPage: { type: integer }
pageCount: { type: integer }
mapIds: { type: array, items: { type: string } }
mapInfos:
type: object
additionalProperties:
type: array
items: { $ref: "#/components/schemas/MapVersionInfo" }
allMapIds: { type: array, items: { type: string } }
MapMetadata:
description: metadata 返回的 JSON（图形服务 原样返回，可能含字符串 JSON 字段）
type: object
additionalProperties: true
# ---------- Query ----------
QueryFeaturesRequest:
type: object
required: [querytype]
properties:
querytype: { type: string, enum: [point, rect, condition, expresion] }
x: { type: number }
y: { type: number }
pixelsize: { type: number }
x1: { type: number }
y1: { type: number }
x2: { type: number }
y2: { type: number }
expr: { type: string }
condition: { type: string }
bounds:
type: string
description: >-
condition 查询的空间范围，必须是字符串："x1,y1,x2,y2" / "[x1,y1,x2,y2]"，
或 "x,y;x,y;..."（折线，首尾相同为多边形）。传 JSON 数组会被转成空串、过滤静默失效。
zoom: { type: integer, default: 1 }
limit: { type: integer }
fields: { type: string }
geom:
type: boolean
description: >-
命令路由开关（不是返回几何的开关）：缺省按图打开方式；false 强制内存进程，
condition 会返回 "not support query type!"。
layername: { type: string }
QueryFeaturesResponse:
type: object
properties:
result:
oneOf:
- type: array
items: { type: object }
- type: object
properties:
features:
type: array
items: { type: object }
total: { type: integer }
CoordTransformRequest:
type: object
required: [srs, crs, points]
properties:
srs: { type: string, example: "EPSG:4326", description: 源坐标系 }
crs: { type: string, example: "EPSG:3857", description: 目标坐标系 }
points: { type: string, example: "116.39,39.9;121.47,31.23", description: '多点串 "x,y;x,y"' }
fourParameter: { type: string, example: "0,0,1,0", description: "xOff,yOff,scale,rotRad" }
isInverseFourParamter: { type: boolean, description: 反向应用四参数（后端拼写 Paramter） }
# ---------- Data storage ----------
KvSaveRequest:
type: object
properties:
value: { type: string }
prop: { type: string }
KvMultipleEntry:
type: object
required: [key]
properties:
key: { type: string }
value: { type: string }
prop: { type: string }
ttl: { type: string, description: 秒数（字符串） }
# ---------- Full-text search ----------
FullSearchDocument:
type: object
description: 全文搜索文档
required: [id]
properties:
id: { type: string, description: 全库唯一，必填 }
map_ver: { type: string, example: "sys_zp_v1" }
content: { type: string, description: 被索引的文本 }
type: { type: integer, description: "1 单行文字 / 2 多行 / 3 属性注记 / 4 块属性注记 / 5 图层 / 6 块名 / 7 线型 / 8 填充 / 9 自定义" }
min_x: { type: number }
min_y: { type: number }
max_x: { type: number }
max_y: { type: number }
props: { type: object, description: 任意附加属性（原样 JSON） }
create_time: { type: string, format: date-time }
workspace: { type: string, description: '默认工作区要显式写 "_"' }
data: { type: string }
FullSearchQuery:
type: object
description: 全文搜索请求（POST 走 JSON，GET 走同名 query）
properties:
query: { type: string }
map_ver: { type: string, description: 多个逗号分隔；纯 mapid 取最新版本 }
type: { type: string, example: "1-3,6" }
workspace: { type: string, description: '多个逗号分隔；缺省 "_"，"*" 查全部' }
limit: { type: integer, default: 10 }
offset: { type: integer, default: 0 }
fields: { type: string }
facet: { type: boolean }
bounding_box: { type: string, example: "[0,0,1000,1000]" }
time_range: { type: string, example: "2023-01-01~2023-12-31" }
# ---------- AI ----------
VectorSearchRequest:
type: object
required: [query]
properties:
query: { type: string }
numDocuments: { type: integer, default: 20 }
collection: { type: string, default: "vj" }
where: { type: string }
whereDocument: { type: string }
searchDescription: { type: string }
disableSplitSentence: { type: boolean, default: false }
disableSearchKnowledge: { type: boolean, default: false }
documents:
type: array
items:
type: object
properties:
content: { type: string }
metadata: { type: object }
paths:
# ==========================================================
# 1. Map Management
# ==========================================================
/api/v1/map/uploads:
post:
tags: [Map Management]
summary: 上传 DWG（multipart）
description: |
服务端只取第一个文件部分，表单字段（md5、secretKey 等）一律不读；
文件按内容 md5 命名。加密只能在首次 openmap 时设。
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [file]
properties:
file: { type: string, format: binary }
md5: { type: string, description: 后端不读（官方 SDK 会带上，无害） }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/UploadResponse" }
examples:
sample:
value:
fileid: "caf27de8a225"
mapid: "caf27de8a225"
uploadname: "my.dwg"
/api/v1/map/openmap/{mapid}:
post:
tags: [Map Management]
summary: 打开地图
description: |
打开一张地图。请求体中只有 `mapid` 必填（且需与 URL path 中的 `{mapid}` 一致）。
`fileid` / `uploadname` 选填：
- 首次打开刚上传的新图：建议带上 `fileid`（取自 `POST /api/v1/map/uploads` 的返回）。
- 已经存在的图：可只传 `mapid`，服务端会按 mapid 自行定位文件。
parameters:
- $ref: "#/components/parameters/MapIdPath"
- name: version
in: query
schema: { type: string, default: v1 }
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/OpenMapRequest" }
examples:
new_upload:
summary: 首次打开新上传的图（带 fileid，GeomRender）
value:
mapid: "demo_123"
fileid: "caf27de8a225"
uploadname: "caf27de8a225.dwg"
geom: true
existing:
summary: 打开已存在的图（仅 mapid，GeomRender）
value:
mapid: "demo_123"
geom: true
memory:
summary: 内存模式（Memory，geom 为 false 或缺省）
value:
mapid: "demo_123"
geom: false
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/OpenMapResponse" }
/api/v1/map/cmd/closemap/{mapid}/{version}:
get:
tags: [Map Management]
summary: 关闭地图（SDK 走 GET，图形服务 POST 空体会 500）
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/CmdBoolResult" }
/api/v1/map/cmd/deletemap/{mapid}/{version}:
get:
tags: [Map Management]
summary: 删除地图
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
- name: deleteDwgFile
in: query
description: true=强制删除源文件；缺省时是否删除取决于服务端 noAutoDeleteDwgFile 配置。注意 openapi/旧文档的 keepSource 参数后端没有消费点。
schema: { type: boolean, default: false }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/CmdBoolResult" }
/api/v1/map/cmd/listmaps/_/v1:
get:
tags: [Map Management]
summary: 列出地图
description: |
非 root 默认隐藏 `ns_` 前缀（config map_list_exclude_prefix），root 隐藏 `ns_temp_`；`temp_` 不隐藏。
`mapIds` 过滤须 POST JSON body `{"mapIds":[...]}`。
parameters:
- name: curPage
in: query
description: 页码（1 起，与 pageCount 同时 >0 才分页并改回分页信封）。旧文档的 keyword/page/pageSize 无消费点
schema: { type: integer }
- name: pageCount
in: query
schema: { type: integer }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/ListMapsResponse" }
/api/v1/map/cmd/metadata/{mapid}/{version}:
get:
tags: [Map Management]
summary: 获取地图元数据
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
# 本接口在源码中不读业务参数；官方文档记载的 enableEditMeta/fileid 均无消费点
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/MapMetadata" }
# ==========================================================
# 2. Tiles & Styles
# ==========================================================
/api/v1/map/tile/{mapid}/{version}/{layer}/{z}/{x}/{y}:
get:
tags: [Tiles & Styles]
summary: 栅格瓦片
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
- { name: layer, in: path, required: true, schema: { type: string } }
- { name: z, in: path, required: true, schema: { type: integer } }
- { name: x, in: path, required: true, schema: { type: integer } }
- { name: y, in: path, required: true, schema: { type: integer } }
- name: tag
in: query
schema: { type: string, description: fileid，用来让 CDN 缓存失效 }
responses:
"200":
description: PNG 瓦片字节流
content:
image/png:
schema: { type: string, format: binary }
/api/v1/map/tile/{mapid}/{version}/{layer}/{z}/{x}/{y}.mvt:
get:
tags: [Tiles & Styles]
summary: 矢量瓦片
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
- { name: layer, in: path, required: true, schema: { type: string, default: main } }
- { name: z, in: path, required: true, schema: { type: integer } }
- { name: x, in: path, required: true, schema: { type: integer } }
- { name: y, in: path, required: true, schema: { type: integer } }
responses:
"200":
description: MVT 二进制
content:
application/vnd.vjmap-vector-tile:
schema: { type: string, format: binary }
/api/v1/map/cmd/wms/{mapid}/{version}:
get:
tags: [Tiles & Styles]
summary: WMS 单张出图
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
- name: bbox
in: query
required: true
schema: { type: string, example: "{bbox-epsg-3857}" }
- name: srs
in: query
schema: { type: string, default: "EPSG:3857" }
- name: width
in: query
schema: { type: integer, default: 256 }
- name: height
in: query
schema: { type: integer, default: 256 }
- name: layers
in: query
description: 样式名（注意是复数 layers，非 layer）
schema: { type: string }
- name: crs
in: query
description: 坐标系别名（与 srs 等价，后端两者都读）
schema: { type: string }
- name: transparent
in: query
description: 默认 true；为 false 时可用 backgroundColor 指定底色
schema: { type: string, default: "true" }
- name: backgroundColor
in: query
description: '"r,g,b" 或 "r,g,b,a" 字符串，仅 transparent=false 生效'
schema: { type: string }
- name: fourParameter
in: query
schema: { type: string }
- name: useImageRotate
in: query
schema: { type: boolean }
responses:
"200":
description: PNG
content:
image/png:
schema: { type: string, format: binary }
/api/v1/service/wms:
get:
tags: [Tiles & Styles]
summary: WMS 多图叠加
description: >-
mapid/version/layers/crs/fourParameter 均为 "_," 分隔的等长数组，
长度不一致返回 paramter error。不支持 .mvt。
parameters:
- { name: mapid, in: query, required: true, schema: { type: string, example: "a_,b_,c" } }
- { name: version, in: query, required: true, schema: { type: string, example: "v1_,v1_,v1" } }
- { name: layers, in: query, required: true, schema: { type: string, example: "_,_," } }
- { name: crs, in: query, required: true, schema: { type: string, example: "_,_," } }
- { name: fourParameter, in: query, required: true, schema: { type: string, example: "_,_," } }
- { name: bbox, in: query, required: true, schema: { type: string, example: "{bbox-epsg-3857}" } }
- { name: srs, in: query, schema: { type: string, default: "EPSG:3857" } }
- { name: width, in: query, schema: { type: integer, default: 256 } }
- { name: height, in: query, schema: { type: integer, default: 256 } }
- name: transparent
in: query
description: Go 端会转发到底层单图 wms；backgroundColor 则不转发（仅单图 cmd/wms 有效）
schema: { type: string, default: "true" }
responses:
"200":
description: PNG
content:
image/png:
schema: { type: string, format: binary }
/api/v1/map/cmd/thumbnail/{mapid}/{version}:
get:
tags: [Tiles & Styles]
summary: 缩略图
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
- { name: width, in: query, schema: { type: integer, default: 200 } }
- { name: height, in: query, schema: { type: integer, default: 200 } }
- { name: darkTheme, in: query, schema: { type: boolean }, description: 暗色主题（仅这三个参数有消费点） }
responses:
"200":
description: PNG
content:
image/png:
schema: { type: string, format: binary }
/api/v1/map/cmd/createMapStyle/{mapid}/{version}:
post:
tags: [Tiles & Styles]
summary: 创建自定义样式
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
stylename: { type: string, description: 样式名（后端读 stylename，不读 name）；缺省为系统样式 }
geom: { type: boolean, description: "true 几何样式（s 前缀），false 栅格样式（m 前缀）" }
layeron: { type: string }
layeroff: { type: string }
backcolor: { type: string }
clipbounds: { type: string }
expression: { type: string }
lineweight: { type: string }
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
stylename: { type: string, example: "sfbd35705c" }
# ==========================================================
# 3. Query
# ==========================================================
/api/v1/map/cmd/queryFeatures/{mapid}/{version}:
post:
tags: [Query]
summary: 要素查询（点 / 矩形 / 条件 / 表达式）
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/QueryFeaturesRequest" }
examples:
rect:
summary: 按矩形查 10 条
value:
querytype: rect
x1: 587227463.27
y1: 3103509765.63
x2: 588006538.39
y2: 3104288840.75
limit: 10
fields: "name,objectid,layername"
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/QueryFeaturesResponse" }
/api/v1/map/cmd/coordtransform/_/_:
post:
tags: [Query]
summary: 坐标变换
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/CoordTransformRequest" }
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
points:
type: array
description: 与入参 points 顺序一一对应的 [x, y]
items: { type: array, items: { type: number } }
examples:
sample:
value:
points: [[12957588.73, 4851421.18]]
# ==========================================================
# 4. Analysis (pass-through 风格)
# ==========================================================
/api/v1/map/cmd/mapDiff/_null/v1:
post:
tags: [Analysis]
summary: 两张图差异分析
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mapid1: { type: string }
version1: { type: string }
mapid2: { type: string }
version2: { type: string }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/CmdBoolResult" }
/api/v1/map/cmd/extractTable/_null/v1:
post:
tags: [Analysis]
summary: 抽取 CAD 中的表格
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mapid: { type: string }
version: { type: string }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/CmdBoolResult" }
# ==========================================================
# 5. Compose & Export
# ==========================================================
/api/v1/map/cmd/exportPdf/{mapid}/{version}:
post:
tags: [Compose & Export]
summary: 导出 PDF
description: |
ODA PDF 导出选项，不支持 bounds/width/height/scale/outName。
cmd 路由对空 JSON body 的 POST 回 500 param error——无参数时用 GET。
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
pageWidth: { type: number, description: 纸张宽（mm），与 pageHeight 同时给才生效 }
pageHeight: { type: number, description: 纸张高（mm） }
pageLeftMargin: { type: number, default: 0 }
pageRightMargin: { type: number, default: 0 }
pageTopMargin: { type: number, default: 0 }
pageBottomMargin: { type: number, default: 0 }
bZoomToExtents: { type: boolean, default: true }
bActiveLayout: { type: boolean, default: true }
geomDPI: { type: integer, default: 600 }
colorImagesDPI: { type: integer, default: 400 }
bwImagesDPI: { type: integer, default: 400 }
isBlackWhiteMode: { type: boolean, default: false }
isGrayMode: { type: boolean, default: false }
bEmbededTTF: { type: boolean, default: false }
title: { type: string, default: "PDF File" }
author: { type: string, default: "vjmap.com" }
pdfPath: { type: string, description: 缺省写入 data/download、按参数 hash 命名 }
additionalProperties: true
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
path: { type: string, example: "download/7733d6c688.pdf" }
status: { type: boolean }
/api/v1/map/cmd/exportDxf/{mapid}/{version}:
post:
tags: [Compose & Export]
summary: 导出 DXF
description: |
整库导出，不支持裁剪/选层。
cmd 路由对空 JSON body 的 POST 回 500 param error——无参数时用 GET。
parameters:
- $ref: "#/components/parameters/MapIdPath"
- $ref: "#/components/parameters/VersionPath"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
filename: { type: string, description: 输出名（自动补 .dxf）；缺省 <源文件名>_.dxf }
cadVersion: { type: string, example: "2018", description: "2000/2004/2007/2010/2013/2018；* = 沿用源图版本" }
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
status: { type: boolean }
fileid: { type: string, example: "c177098c15d1_.dxf", description: 写入 mapfiles 目录的文件名 }
error: { type: string }
# ==========================================================
# 7. Workspace
# ==========================================================
/api/v1/service/getWorkspace:
get:
tags: [Workspace]
summary: 列出所有工作区
responses:
"200": { description: OK }
/api/v1/service/workspaceCreate:
post:
tags: [Workspace]
summary: 新建工作区
description: '默认 casbin 策略仅 root 可调（admin/guest 被 /api/v1/service/workspace* 拒，403 权限不足）。'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name]
properties:
name: { type: string }
alias: { type: string }
isPublic: { type: boolean }
workDir: { type: string }
disableFullSearch: { type: boolean }
# WsData 请求结构无 idleCloseTime/description/token/createUser
responses:
"200": { description: OK }
/api/v1/service/workspaceModify:
post:
tags: [Workspace]
summary: 修改工作区
description: |
服务端按 name 定位，只更新 alias/isPublic/disableFullSearch，
未给的这三项被重置为零值；workDir/idleCloseTime/createTime 传了也不改。仅 root 可调。
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name]
properties:
# ModifyWorkSpace 绑定完整 MapWorkspace，但只更新 alias/isPublic/disableFullSearch
name: { type: string }
alias: { type: string }
isPublic: { type: boolean }
disableFullSearch: { type: boolean }
workDir: { type: string, description: 不会被修改 }
idleCloseTime: { type: integer, description: 不会被修改 }
responses:
"200": { description: OK }
/api/v1/service/workspaceDelete/{name}:
delete:
tags: [Workspace]
summary: 删除工作区
description: '不可逆——停进程、删全文索引并 os.RemoveAll 整个工作目录（全部图/瓦片）。仅 root 可调。'
parameters:
- name: name
in: path
required: true
schema: { type: string }
responses:
"200": { description: OK }
/api/v1/service/workspaceStatus:
get:
tags: [Workspace]
summary: 全部工作区状态
description: '返回所有命名工作区的 WsDataStatus 数组（未起进程的 ProcIsNull: true）；一个都没有时为 null。仅 root 可调。'
responses:
"200": { description: OK }
# ==========================================================
# 8. Data Storage (KV)
# ==========================================================
/api/v1/service/data/{key}:
get:
tags: [Data Storage]
summary: 读单/多键
parameters:
- name: key
in: path
required: true
schema: { type: string, description: 多键用 `;;` 连接 }
- name: retDataType
in: query
schema: { type: string, enum: [value, prop, valueprop] }
responses:
"200":
description: OK
content:
application/json:
schema: { $ref: "#/components/schemas/ServiceOk" }
post:
tags: [Data Storage]
summary: 写单键
parameters:
- name: key
in: path
required: true
schema: { type: string }
- name: ttl
in: query
schema: { type: integer }
description: |
只用 JSON body（ShouldBindJSON）。raw body 分支不可用：body 已被 JSON 解码器读走，
小 body 存成 ""、大 body 被截断；value/prop 非字符串同样静默存成 ""。二进制请 base64 后放 value。
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/KvSaveRequest" }
responses:
"200": { description: OK }
delete:
tags: [Data Storage]
summary: 删除键
parameters:
- name: key
in: path
required: true
schema: { type: string }
- name: isPrefix
in: query
schema: { type: boolean }
responses:
"200": { description: OK }
/api/v1/service/datas:
post:
tags: [Data Storage]
summary: 批量写键
description: '四个字段都必须是字符串（含 ttl）；绑定失败返回 HTTP 403 {code:7, msg:"json: cannot unmarshal ..."}，不是权限问题。'
requestBody:
required: true
content:
application/json:
schema:
type: array
items: { $ref: "#/components/schemas/KvMultipleEntry" }
responses:
"200": { description: OK }
/api/v1/service/datakeys:
get:
tags: [Data Storage]
summary: 按前缀列出键
description: |
SQL `key like 'data_<prefix>%'`：`_`/`%` 为通配符、ASCII 不分大小写、`'` 会破坏 SQL。
parameters:
- name: prefix
in: query
schema: { type: string }
- name: retDataType
in: query
schema: { type: string, enum: [value, prop, valueprop] }
- name: isSys
in: query
description: 'true 时 prefix 不补 data_，返回整行对象 {keys:[{Key,Value,Prop,Ttl}]}'
schema: { type: string, enum: ["true"] }
responses:
"200": { description: OK }
# ==========================================================
# 9. Full-text Search
# ==========================================================
/api/v1/service/fullsearch/search:
get:
tags: [Full-text Search]
summary: 全文检索（GET，参数走 query，字段同 FullSearchQuery）
parameters:
- name: query
in: query
schema: { type: string }
- name: limit
in: query
schema: { type: integer, default: 10 }
- name: offset
in: query
schema: { type: integer, default: 0 }
- name: map_ver
in: query
schema: { type: string }
- name: type
in: query
schema: { type: string }
- name: workspace
in: query
schema: { type: string }
- name: fields
in: query
schema: { type: string }
- name: bounding_box
in: query
schema: { type: string }
- name: time_range
in: query
schema: { type: string }
responses:
"200": { description: OK }
post:
tags: [Full-text Search]
summary: 全文检索（POST，参数走 JSON）
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/FullSearchQuery" }
responses:
"200": { description: OK }
/api/v1/service/fullsearch/add:
post:
tags: [Full-text Search]
summary: 索引单条文档
description: 'body 必须包一层 `{document: {...}}`；document.id 不能为空。'
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [document]
properties:
document: { $ref: "#/components/schemas/FullSearchDocument" }
responses:
"200": { description: OK }
/api/v1/service/fullsearch/delete:
delete:
tags: [Full-text Search]
summary: 删除文档
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [id]
properties:
id: { type: string }
responses:
"200": { description: OK }
# ==========================================================
# 10. Symbols
# ==========================================================
/api/v1/service/symbol/categories:
get:
tags: [Symbols]
summary: 符号分类
responses:
"200":
description: OK
content:
application/json:
examples:
sample:
value:
status: ok
data:
- id: default
name: 默认分类
createTime: "2026-04-10 11:29:15"
/api/v1/service/symbol/list/{categoryId}:
get:
tags: [Symbols]
summary: 符号列表（可分类+分页）
parameters:
- name: categoryId
in: path
required: true
schema: { type: string }
- name: page
in: query
schema: { type: integer, default: 1 }
- name: pageSize
in: query
schema: { type: integer, default: 20 }
responses:
"200": { description: OK }
/api/v1/service/symbol/{id}:
get:
tags: [Symbols]
summary: 获取单个符号
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
"200": { description: OK }
"404": { description: 符号不存在 }
# ==========================================================
# 11. System
# ==========================================================
/heart:
get:
tags: [System]
summary: 心跳（顶层路径，不走 /api/v1 前缀）
security: []
responses:
"200":
description: OK
content:
application/json:
examples:
sample: { value: { status: ok } }
/version:
get:
tags: [System]
summary: 版本信息（顶层路径）
security: []
responses:
"200": { description: OK }
/api/v1/map/cmd/runstatus/_/v1:
get:
tags: [System]
summary: 运行状态（图形服务命令）
parameters:
- name: detail
in: query
schema: { type: boolean, default: true }
responses:
"200": { description: OK }
/api/v1/map/cmd/viewlogs/_/v1:
get:
tags: [System]
summary: 查看日志（图形服务命令）
parameters:
- name: time
in: query
description: 最近 N 分钟的日志
schema: { type: integer, default: 60 }
- name: record
in: query
schema: { type: integer, default: 100 }
responses:
"200":
description: OK
content:
text/plain:
schema: { type: string }
# ==========================================================
# 12. Misc Services
# ==========================================================
/api/v1/service/qrcode:
get:
tags: [Misc Services]
summary: 生成二维码 PNG
parameters:
- name: content
in: query
required: true
schema: { type: string }
- name: size
in: query
schema: { type: integer, default: 256 }
responses:
"200":
description: PNG
content:
image/png:
schema: { type: string, format: binary }
/api/v1/service/fonts/{fontstack}/{range}.pbf:
get:
tags: [Misc Services]
summary: 字体 glyphs
parameters:
- name: fontstack
in: path
required: true
schema: { type: string, example: "Open Sans Regular" }
- name: range
in: path
required: true
schema: { type: string, example: "0-255" }
responses:
"200":
description: PBF
content:
application/x-protobuf:
schema: { type: string, format: binary }
/api/v1/service/uploadImg:
post:
tags: [Misc Services]
summary: 上传图片（JWT token + 固定 Basic Authorization）
description: |
路由在全局 JWT/casbin 之后注册，普通 token 照常需要；处理函数另外要求
`Authorization: Basic X3ZqbWFwQF8=`，并通过 `Uri` 头告知服务端存储目录。
响应 `{code:0, path: Uri+文件名, url: ImgHost 头+文件名}`。
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [upload]
properties:
# 注意：字段名是 upload（后端 c.FormFile("upload")），不是 file
upload: { type: string, format: binary }
watermark: { type: boolean }
responses:
"200": { description: OK }
# ==========================================================
# 13. AI
# ==========================================================
/api/v1/service/vectorSearch:
post:
tags: [AI]
summary: 相似性检索
requestBody:
required: true
content:
application/json:
schema: { $ref: "#/components/schemas/VectorSearchRequest" }
responses:
"200": { description: OK }
"500":
description: embedding 模型未配置
content:
application/json:
examples:
missingModel:
value:
code: 8
data: {}
msg: "bge-large-zh-v1.5-f16.gguf is not exist"
/api/v1/service/chatFaq:
get:
tags: [AI]
summary: FAQ 知识库
responses:
"200": { description: OK }
/api/v1/service/vectorDocs:
get:
tags: [AI]
summary: 向量库文档元数据
responses:
"200": { description: OK }
