TappoCloud/store/openapi.yaml

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]