chore(contracts): 同步契约到 v0.2.0(rest-api / data-models / model-formats)

Web 端需求变更带来的契约字段级改动:
- MotionFormat 枚举新增 vmd(MikuMikuDance 动作数据)
- rest-api 服务地址说明改为双端口语义(软件 API 端口给客户端 / 管理端端口给浏览器)
- model-formats 新增 §2.3 VMD 解析约定(标准 MMD 骨架、腿部 IK/FK 判定、手性转换)

三库契约文件保持逐字节一致。
This commit is contained in:
2026-09-15 08:45:06 +08:00
parent 3ba8103723
commit 8f303c0595
4 changed files with 57 additions and 12 deletions
+9 -6
View File
@@ -1,7 +1,7 @@
openapi: 3.0.3
info:
title: OpenDance Studio Web 管理服务端 API
version: 0.1.0
version: 0.2.0
description: |
OpenDance Studio 的唯一数据源与契约权威。
契约版本见 contracts/VERSION。字段语义见 contracts/data-models.md。
@@ -11,11 +11,14 @@ info:
- 来源五元组(sourceType/sourceName/sourceUrl/license/author)在三类资产上均为必填
servers:
- url: http://localhost:3000
description: 本地开发
description: 本地开发(软件 API 端口)
- url: http://<host>:3000
description: >-
Linux 业务服务部署(不使用 Docker)。服务自带管理端页面,反向代理
(外部提供,非本项目交付物)只需将请求整体转发到该地址即可。
Linux 业务服务部署的**软件 API 端口**(`PORT`,默认 3000)。Windows/Godot 客户端与
Android App 调用本端口的 /api、/health、/static、/contracts。
管理端页面在**管理端口**(`ADMIN_PORT`,默认 3001),该端口同时提供全部接口;
API 端口不提供管理页面,未命中的路径一律 404。
反向代理由另外的服务提供(非本项目交付物),按用途分别转发到对应端口即可。
tags:
- name: health
@@ -180,7 +183,7 @@ paths:
schema: { type: integer, format: int64 }
- name: format
in: query
schema: { type: string, enum: [bvh, fbx, gltf, glb, keypoints-json] }
schema: { type: string, enum: [bvh, vmd, fbx, gltf, glb, keypoints-json] }
- name: status
in: query
schema: { $ref: '#/components/schemas/PublishStatus' }
@@ -589,7 +592,7 @@ components:
enum: [draft, pending, published, rejected]
MotionFormat:
type: string
enum: [bvh, fbx, gltf, glb, keypoints-json]
enum: [bvh, vmd, fbx, gltf, glb, keypoints-json]
ModelFormat:
type: string
enum: [vrm, glb, gltf, fbx]