{"openapi":"3.1.0","info":{"title":"OK.one 开放数据 API","version":"1.0.0","description":"只读、免鉴权、允许跨域(CORS *)。返回企业评分、评分分布与用户评价。内容可用于检索与引用,请注明来源并链接回对应页面。"},"servers":[{"url":"https://ok.one"}],"paths":{"/api/companies/":{"get":{"summary":"企业列表","operationId":"listCompanies","parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"分类 id,如 electronics_technology"},{"name":"q","in":"query","schema":{"type":"string"},"description":"名称/域名模糊搜索"},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","reviews","recent"],"default":"score"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":60}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}}}}}}}}},"/api/companies/{slug}":{"get":{"summary":"单个企业详情(含最新一页评价)","operationId":"getCompany","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"企业域名,如 www.otterbox.com 或 metlifepetinsurance.com(含点,结尾不带斜杠,部分带 www. 前缀;裸域/www. 只收录其一时,另一形态 308 到实际 slug)"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"company":{"$ref":"#/components/schemas/Company"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"ratingCounts":{"type":"array","items":{"type":"integer"},"description":"[5星,4星,3星,2星,1星] 的精确条数"},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"404":{"description":"未收录该企业"}}}},"/api/categories/":{"get":{"summary":"完整分类树(顶级分类 + 子类)","operationId":"listCategories","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}}}}}}},"/api/search/":{"get":{"summary":"企业搜索(支持中文词跨语言扩展)","operationId":"searchCompanies","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"perPage","in":"query","schema":{"type":"integer","maximum":100,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"total":{"type":"integer","description":"真实命中总数(data 只是当前页)"},"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Company":{"type":"object","description":"字段可能随数据补全逐步增加(additionalProperties)","additionalProperties":true,"properties":{"slug":{"type":"string","description":"即企业域名,也是页面路径 /review/{slug}"},"name":{"type":"string"},"domain":{"type":"string"},"categoryId":{"type":"string"},"categoryName":{"type":"string"},"trustScore":{"type":"number","description":"综合评分 1-5"},"stars":{"type":"number","description":"星级展示值,可为半星(如 4.5)"},"reviewCount":{"type":"integer"},"distribution":{"type":"array","items":{"type":"number"},"description":"5→1 星的百分比数组"},"location":{"type":"string"},"verified":{"type":"boolean"},"summary":{"type":"string"},"updatedAt":{"type":"string","format":"date-time","description":"本条数据最后更新时间"}}},"Review":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer"},"author":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string","description":"中文(缺译文时为原文)"},"body":{"type":"string"},"titleEn":{"type":"string","description":"英文原文"},"bodyEn":{"type":"string"},"publishedDate":{"type":"string"},"verified":{"type":"boolean"}}},"Category":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string","description":"中文名"},"nameEn":{"type":"string"},"children":{"type":"array","items":{"type":"object"},"description":"子分类,结构同上(无 children)"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}