{
  "openapi": "3.1.0",
  "info": {
    "title": "Star Wiki API",
    "version": "1.0.0",
    "description": "Star Wiki（github-wiki.com）公开只读 API：检索 GitHub Star 项目的中文知识库（介绍、Wiki、FAQ、专题、图谱）与 X 转发收藏（原文与 AI 中文梗概）。无需认证。中文或英文关键词均可搜索。",
    "contact": {
      "name": "Star Wiki",
      "url": "https://www.github-wiki.com"
    }
  },
  "servers": [
    {
      "url": "https://www.github-wiki.com",
      "description": "生产环境"
    }
  ],
  "tags": [
    {
      "name": "projects",
      "description": "GitHub 项目中文知识库"
    },
    {
      "name": "reposts",
      "description": "X 转发收藏"
    },
    {
      "name": "search",
      "description": "全站搜索"
    },
    {
      "name": "meta",
      "description": "站点元信息"
    }
  ],
  "paths": {
    "/api/projects": {
      "get": {
        "operationId": "listProjects",
        "summary": "分页获取项目列表",
        "description": "按 Star 时间倒序返回项目卡片数据，可按语言过滤。用于浏览与发现项目。",
        "tags": [
          "projects"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "页码"
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 21
            },
            "description": "每页数量"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "按编程语言过滤，如 TypeScript、Python"
          },
          {
            "name": "sortBy",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "stars",
                "synced_at",
                "starred_at",
                "id"
              ],
              "default": "starred_at"
            },
            "description": "排序字段"
          }
        ],
        "responses": {
          "200": {
            "description": "项目分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/projects/{id}": {
      "get": {
        "operationId": "getProjectById",
        "summary": "获取项目详情（中文介绍、Wiki、FAQ）",
        "description": "返回单个项目的完整知识库内容，含 AI 生成的中文介绍、一句话梗概、Wiki 章节、SEO 元信息与 FAQ。回答\"这个项目是什么/怎么用\"类问题的首选接口。",
        "tags": [
          "projects"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "项目数字 ID（可从 listProjects 获得）"
          }
        ],
        "responses": {
          "200": {
            "description": "项目详情",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectDetailResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchProjects",
        "summary": "全文搜索项目（中英文均可）",
        "description": "按语义相关度 + 全文匹配检索项目，支持中文关键词（搜索 AI 生成的中文介绍与 Wiki 内容）。找\"某类工具/某个问题方案\"时使用。",
        "tags": [
          "search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "description": "搜索关键词，中英文均可"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "页码"
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 48,
              "default": 10
            },
            "description": "每页数量"
          }
        ],
        "responses": {
          "200": {
            "description": "搜索结果（按相关度排序）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/reposts": {
      "get": {
        "operationId": "listReposts",
        "summary": "获取 X 转发收藏（原文 + AI 中文梗概）",
        "description": "分页返回 X（Twitter）转发收藏，可按关键词过滤。关键词同时匹配推文原文、AI 中文梗概、原作者与链接文章标题。",
        "tags": [
          "reposts"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "可选过滤关键词，匹配原文/梗概/作者/文章标题"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "页码"
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 6,
              "maximum": 48,
              "default": 24
            },
            "description": "每页数量"
          }
        ],
        "responses": {
          "200": {
            "description": "转发分页结果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepostListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "健康检查",
        "description": "返回站点运行状态，用于探活。",
        "tags": [
          "meta"
        ],
        "responses": {
          "200": {
            "description": "站点正常",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源不存在",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiError"
            }
          }
        }
      }
    },
    "schemas": {
      "ApiEnvelope": {
        "type": "object",
        "description": "所有接口的统一响应包装",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "是否成功"
          },
          "message": {
            "type": "string",
            "description": "人类可读的提示信息（中文）"
          },
          "data": {
            "type": "object",
            "description": "业务数据"
          }
        },
        "required": [
          "success",
          "message"
        ]
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "message": {
            "type": "string",
            "description": "错误信息（中文）"
          },
          "errorCode": {
            "type": "string",
            "description": "机器可读错误码，如 PROJECT_NOT_FOUND"
          },
          "details": {
            "description": "可选的补充信息"
          }
        },
        "required": [
          "success",
          "message",
          "errorCode"
        ]
      },
      "ProjectSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "full_name": {
            "type": "string",
            "description": "仓库全名，如 vercel/next.js"
          },
          "name": {
            "type": "string"
          },
          "owner": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "GitHub 原始英文描述"
          },
          "one_line_intro": {
            "type": "string",
            "description": "AI 生成的一句话中文介绍"
          },
          "chinese_intro": {
            "type": "string",
            "description": "AI 生成的中文详细介绍"
          },
          "html_url": {
            "type": "string",
            "format": "uri"
          },
          "stars": {
            "type": "integer"
          },
          "language": {
            "type": "string",
            "description": "主要编程语言"
          }
        },
        "required": [
          "id",
          "full_name"
        ]
      },
      "ProjectWikiDocument": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "章节标题（中文）"
          },
          "content": {
            "type": "string",
            "description": "章节正文（中文）"
          }
        }
      },
      "FaqItem": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          }
        }
      },
      "ProjectDetail": {
        "type": "object",
        "description": "项目完整知识库内容",
        "allOf": [
          {
            "$ref": "#/components/schemas/ProjectSummary"
          },
          {
            "type": "object",
            "properties": {
              "project_type": {
                "type": "string",
                "description": "项目形态：app/library/cli/plugin/ui/template/docs/awesome-list 等"
              },
              "topics": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "GitHub topics"
              },
              "wiki_documents": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProjectWikiDocument"
                },
                "description": "AI 生成的中文 Wiki 章节（定位/解决问题/场景/安装/使用等）"
              },
              "faq_items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FaqItem"
                },
                "description": "常见问题（中文）"
              },
              "mind_map": {
                "type": "object",
                "description": "项目结构思维导图（可能为 null）"
              }
            }
          }
        ]
      },
      "ProjectListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "projects": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProjectSummary"
                }
              },
              "total": {
                "type": "integer"
              },
              "page": {
                "type": "integer"
              },
              "totalPages": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ProjectDetailResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "project": {
                "$ref": "#/components/schemas/ProjectDetail"
              }
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "projects": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ProjectSummary"
                }
              },
              "total": {
                "type": "integer"
              },
              "page": {
                "type": "integer"
              },
              "totalPages": {
                "type": "integer"
              }
            }
          }
        }
      },
      "RepostItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "tweet_id": {
            "type": "string",
            "description": "转发推文 ID"
          },
          "original_text": {
            "type": "string",
            "description": "推文原文"
          },
          "original_author_name": {
            "type": "string"
          },
          "original_author_handle": {
            "type": "string"
          },
          "original_url": {
            "type": "string",
            "format": "uri",
            "description": "原推链接（x.com）"
          },
          "ai_summary_zh": {
            "type": "string",
            "description": "AI 生成的一句话中文梗概"
          },
          "summary_status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "completed",
              "failed",
              "unavailable"
            ]
          },
          "reposted_at": {
            "type": "string",
            "description": "转发时间"
          },
          "link_url": {
            "type": "string",
            "format": "uri",
            "description": "推文内链接展开后的真实地址（可能为 null）"
          },
          "link_title": {
            "type": "string",
            "description": "链接文章标题（可能为 null）"
          }
        }
      },
      "RepostListResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "reposts": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RepostItem"
                }
              },
              "total": {
                "type": "integer"
              },
              "page": {
                "type": "integer"
              },
              "totalPages": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "开发者文档",
    "url": "https://www.github-wiki.com/developers"
  }
}