openapi: 3.0.3 info: title: TappoCloud App Store API description: | Tappo 应用商店公开 API，供 Tappo 客户端获取应用列表、详情和下载。 ## 应用类型 - `system`: 系统应用（官方内置） - `community`: 社区应用（第三方开发） - `external`: 远程应用（SaaS 集成） ## 应用包结构 ``` my-app/ ├── app.yml # 元数据定义 ├── main.py # 后端逻辑 ├── assets/ # 静态资源 │ └── icon.png └── README.md ``` version: 1.0.0 contact: name: Tappo Team url: https://tappo.dev license: name: Proprietary servers: - url: https://store.tappo.dev/api/v1 description: Production - url: http://localhost:8000/api/v1 description: Development tags: - name: Categories description: 应用分类 - name: Apps description: 应用管理 paths: /categories: get: tags: [Categories] summary: 获取分类列表 operationId: listCategories responses: '200': description: 成功 content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/Category' example: items: - slug: security name: 安全工具 description: 密码管理、认证、加密等安全相关应用 icon: shield - slug: productivity name: 效率工具 description: 提升工作效率的自动化工具 icon: zap /apps: get: tags: [Apps] summary: 获取应用列表 operationId: listApps parameters: - name: category in: query description: 按分类筛选 (slug) schema: type: string example: security - name: type in: query description: 按应用类型筛选 schema: type: string enum: [system, community, external] - name: search in: query description: 搜索关键词 (名称/描述) schema: type: string - name: featured in: query description: 仅返回推荐应用 schema: type: boolean - name: sort in: query description: 排序方式 schema: type: string enum: [newest, popular] default: newest - name: page in: query description: 页码 (从 1 开始) schema: type: integer minimum: 1 default: 1 - name: page_size in: query description: 每页数量 schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/AppListResponse' /apps/{app_uid}: get: tags: [Apps] summary: 获取应用详情 operationId: getApp parameters: - name: app_uid in: path required: true description: 应用唯一标识 schema: type: string example: mfa-authenticator responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/AppDetail' '404': description: 应用不存在 content: application/json: schema: $ref: '#/components/schemas/Error' /apps/{app_uid}/download: get: tags: [Apps] summary: 下载应用包 description: | 返回最新版本的下载信息。客户端应使用返回的 `url` 下载 ZIP 包， 下载后验证 `checksum_sha256` 确保完整性。 operationId: downloadApp parameters: - name: app_uid in: path required: true description: 应用唯一标识 schema: type: string example: mfa-authenticator responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/DownloadInfo' '404': description: 应用不存在或无可用版本 content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Category: type: object properties: slug: type: string description: 分类标识符 example: security name: type: string description: 分类名称 example: 安全工具 description: type: string description: 分类描述 example: 密码管理、认证、加密等安全相关应用 icon: type: string description: 图标标识 example: shield required: [slug, name] Developer: type: object properties: id: type: integer format: int64 name: type: string example: Tappo Team avatar_url: type: string format: uri nullable: true verified: type: boolean description: 是否官方认证 example: true required: [id, name, verified] AppSummary: type: object description: 应用列表项 properties: app_uid: type: string description: 应用唯一标识 example: mfa-authenticator name: type: string description: 应用名称 example: MFA 安全令牌 type: type: string enum: [system, community, external] example: system icon_url: type: string format: uri nullable: true example: https://cdn.tappo.dev/apps/mfa/icon.png short_description: type: string example: 管理 TOTP/HOTP 双因素认证令牌 categories: type: array items: type: string example: [security] developer: $ref: '#/components/schemas/Developer' current_version: type: string description: 当前版本号 example: 1.2.0 download_count: type: integer format: int64 example: 1234 is_featured: type: boolean example: true publish_time: type: string format: date-time example: "2025-01-15T10:30:00Z" required: [app_uid, name, type] AppDetail: allOf: - $ref: '#/components/schemas/AppSummary' - type: object properties: description: type: string description: 详细描述 (Markdown) example: | ## MFA 安全令牌 管理您的 TOTP/HOTP 双因素认证令牌。 ### 功能特性 - 支持扫码添加 - 自动计算验证码 - 数据本地加密存储 homepage_url: type: string format: uri nullable: true manifest: $ref: '#/components/schemas/Manifest' version_info: $ref: '#/components/schemas/VersionInfo' Manifest: type: object description: 应用清单 (来自 app.yml) properties: pages: type: array items: type: object properties: id: type: string title: type: string window: type: object properties: width: type: integer height: type: integer commands: type: array items: type: object properties: id: type: string name: type: string description: type: string permissions: type: array items: type: object properties: id: type: string description: type: string VersionInfo: type: object properties: version: type: string example: 1.2.0 release_notes: type: string nullable: true example: "修复了若干 Bug，提升稳定性" min_client_version: type: string nullable: true example: "0.5.0" published_at: type: string format: date-time example: "2025-01-20T08:00:00Z" size_bytes: type: integer format: int64 example: 102400 DownloadInfo: type: object properties: app_uid: type: string example: mfa-authenticator version: type: string example: 1.2.0 url: type: string format: uri description: ZIP 包下载地址 (可能为预签名 URL) example: https://cdn.tappo.dev/apps/mfa/1.2.0/package.zip checksum_sha256: type: string description: SHA256 校验值 example: a1b2c3d4e5f6... size_bytes: type: integer format: int64 example: 102400 required: [app_uid, version, url] AppListResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/AppSummary' page: type: integer example: 1 page_size: type: integer example: 20 total: type: integer description: 总记录数 example: 42 Error: type: object properties: code: type: string example: NOT_FOUND message: type: string example: 应用不存在 required: [code, message]