{"openapi":"3.1.0","info":{"title":"Xingchao Public API","version":"1.0.0","description":"A public, read-only API for GitHub Trending and the 自荐墙 (approved community submissions)."},"servers":[{"url":"https://xingchao.dev"}],"paths":{"/api/v1/health":{"get":{"summary":"Check service and data availability","responses":{"200":{"description":"Service is available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/v1/meta":{"get":{"summary":"Get cache freshness metadata","responses":{"200":{"description":"Freshness metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Meta"}}}}}}},"/api/v1/languages":{"get":{"summary":"List supported time ranges and languages","responses":{"200":{"description":"Supported filters","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/community":{"get":{"summary":"Get approved community submissions (自荐墙)","responses":{"200":{"description":"Approved community submissions shown on the 自荐墙","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunityResponse"}}}},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/v1/trending":{"get":{"summary":"Get a GitHub Trending leaderboard","parameters":[{"name":"since","in":"query","schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"daily"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["all","python","javascript","typescript","go","rust","java","cpp","zh"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/v1/trending/top":{"get":{"summary":"Get a short leaderboard and shareable text","parameters":[{"name":"since","in":"query","schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"daily"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["all","python","javascript","typescript","go","rust","java","cpp","zh"],"default":"all"}},{"name":"limit","in":"query","description":"Optional upper bound applied before n","schema":{"type":"integer","minimum":1,"maximum":25,"default":25}},{"name":"n","in":"query","schema":{"type":"integer","minimum":1,"maximum":15,"default":10}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"503":{"$ref":"#/components/responses/DataUnavailable"}}}},"/api/v1/digest.md":{"get":{"summary":"Get a compact Markdown digest","parameters":[{"name":"since","in":"query","schema":{"type":"string","enum":["daily","weekly","monthly"],"default":"daily"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["all","python","javascript","typescript","go","rust","java","cpp","zh"],"default":"all"}},{"name":"n","in":"query","schema":{"type":"integer","minimum":1,"maximum":15,"default":10}}],"responses":{"200":{"description":"Markdown digest","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid query","content":{"text/markdown":{"schema":{"type":"string"}}}},"503":{"description":"No cached data","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"responses":{"BadRequest":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DataUnavailable":{"description":"No cached data is available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Repo":{"type":"object","required":["rank","owner","repo","author","name","fullName","url","stars","forks","periodStars","starsSince","builtBy"],"properties":{"rank":{"type":"integer"},"owner":{"type":"string"},"repo":{"type":"string"},"author":{"type":"string"},"name":{"type":"string"},"fullName":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"language":{"type":["string","null"]},"languageColor":{"type":["string","null"]},"stars":{"type":"integer"},"forks":{"type":"integer"},"periodStars":{"type":"integer"},"starsSince":{"type":"integer"},"builtBy":{"type":"array","items":{"type":"object"}}}},"TrendingResponse":{"type":"object","required":["ok","app","since","language","fetchedAt","source","count","items"],"properties":{"ok":{"const":true},"app":{"const":"星潮"},"since":{"type":"string","enum":["daily","weekly","monthly"]},"language":{"type":"string"},"fetchedAt":{"type":"string","format":"date-time"},"source":{"type":"string","format":"uri"},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Repo"}},"text":{"type":"string"}}},"Meta":{"type":"object","required":["ok","lastSuccessAt","lastAttemptAt","stale","fetchOk","failures"],"properties":{"ok":{"const":true},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"lastAttemptAt":{"type":["string","null"],"format":"date-time"},"stale":{"type":"boolean"},"fetchOk":{"type":"boolean"},"message":{"type":["string","null"]},"failures":{"type":"array","items":{"type":"string"}}}},"Health":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","required":["app","dataAvailable"],"properties":{"app":{"const":"星潮"},"dataAvailable":{"const":true}}}]},"CommunityItem":{"type":"object","required":["fullName","url","reason","nominator","approvedAt"],"properties":{"fullName":{"type":"string"},"url":{"type":"string","format":"uri"},"reason":{"type":"string","minLength":1,"maxLength":80},"nominator":{"type":["string","null"]},"approvedAt":{"type":"string","format":"date"}}},"CommunityResponse":{"type":"object","required":["ok","updatedAt","count","items"],"properties":{"ok":{"const":true},"updatedAt":{"type":"string","format":"date-time"},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CommunityItem"}}}},"Error":{"type":"object","required":["ok","error","message"],"properties":{"ok":{"const":false},"error":{"type":"string"},"message":{"type":"string"}}}}}}