openapi.yaml 10KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328
  1. openapi: 3.0.3
  2. info:
  3. title: Yico 前台 API
  4. version: 1.0.0
  5. description: |
  6. 對應 docs/api-spec.md。Base URL 實測 https://webdev.yico.tw:8088,path 前綴 /api。
  7. 全部 GET、免認證;{locale} 僅 tw|en;中文以 \uXXXX 跳脫;圖片 URL 含雙斜線。
  8. servers:
  9. - url: https://webdev.yico.tw:8088/api
  10. description: staging(實測)
  11. - url: http://127.0.0.1:8083/api
  12. description: 本地
  13. paths:
  14. /{locale}/news:
  15. get:
  16. summary: 置頂消息+年份清單
  17. parameters:
  18. - $ref: '#/components/parameters/Locale'
  19. responses:
  20. '200':
  21. description: 成功;無置頂資料時回 [](空陣列)
  22. content:
  23. application/json:
  24. schema:
  25. oneOf:
  26. - $ref: '#/components/schemas/TopResponse'
  27. - type: array
  28. maxItems: 0
  29. /{locale}/news/list:
  30. get:
  31. summary: 消息列表
  32. parameters:
  33. - $ref: '#/components/parameters/Locale'
  34. - name: page
  35. in: query
  36. schema: { type: integer, default: 1 }
  37. - name: per_page
  38. in: query
  39. description: 每頁筆數;-1 取全部不分頁
  40. schema: { type: integer, default: 15 }
  41. - name: year
  42. in: query
  43. schema: { type: integer }
  44. - name: month
  45. in: query
  46. description: 需與 year 並用,單獨傳入不過濾
  47. schema: { type: integer }
  48. responses:
  49. '200':
  50. description: 成功
  51. content:
  52. application/json:
  53. schema:
  54. $ref: '#/components/schemas/ListResponse'
  55. /{locale}/news/detail/{id}:
  56. get:
  57. summary: 消息內文
  58. parameters:
  59. - $ref: '#/components/parameters/Locale'
  60. - name: id
  61. in: path
  62. required: true
  63. schema: { type: integer }
  64. - name: preview
  65. in: query
  66. description: preview=1 時 bypass 可見性與有效期(免認證)
  67. schema: { type: string }
  68. responses:
  69. '200':
  70. description: 成功
  71. content:
  72. application/json:
  73. schema:
  74. $ref: '#/components/schemas/DetailResponse'
  75. '404':
  76. description: 不存在或未上架
  77. content:
  78. application/json:
  79. schema:
  80. type: object
  81. properties:
  82. message: { type: string, example: 'news not found' }
  83. /{locale}/esg:
  84. get:
  85. summary: ESG 主視覺+頁籤
  86. parameters:
  87. - $ref: '#/components/parameters/Locale'
  88. responses:
  89. '200':
  90. description: 成功;無 ESG 資料時缺 tab_list 鍵
  91. content:
  92. application/json:
  93. schema:
  94. $ref: '#/components/schemas/EsgMainResponse'
  95. /{locale}/esg/{key}:
  96. get:
  97. summary: ESG 單頁內容
  98. parameters:
  99. - $ref: '#/components/parameters/Locale'
  100. - name: key
  101. in: path
  102. required: true
  103. description: 頁籤 keyword(中文需 URL 編碼)
  104. schema: { type: string }
  105. responses:
  106. '200':
  107. description: '成功;查無資料時同為 200,body 為 {status: fail, message: 查無資料}'
  108. content:
  109. application/json:
  110. schema:
  111. oneOf:
  112. - $ref: '#/components/schemas/EsgContentResponse'
  113. - $ref: '#/components/schemas/FailBody'
  114. components:
  115. parameters:
  116. Locale:
  117. name: locale
  118. in: path
  119. required: true
  120. schema:
  121. type: string
  122. enum: [tw, en]
  123. schemas:
  124. Pagination:
  125. type: object
  126. properties:
  127. page: { type: string, example: '1' }
  128. per_page: { type: string, example: '2' }
  129. total: { type: integer }
  130. total_page: { type: integer }
  131. NewsListItem:
  132. type: object
  133. properties:
  134. id: { type: integer }
  135. categoryId: { type: integer }
  136. category: { type: string }
  137. postDate: { type: string, example: '2015.05.06' }
  138. title: { type: string }
  139. img_pc: { type: string, nullable: true }
  140. img_mobile: { type: string, nullable: true }
  141. written: { type: string }
  142. description: { type: string }
  143. ListResponse:
  144. type: object
  145. properties:
  146. data:
  147. type: object
  148. properties:
  149. pagination: { $ref: '#/components/schemas/Pagination' }
  150. list:
  151. type: array
  152. items: { $ref: '#/components/schemas/NewsListItem' }
  153. TopResponse:
  154. type: object
  155. properties:
  156. data:
  157. type: object
  158. properties:
  159. meta:
  160. type: object
  161. properties:
  162. meta_title: { type: string }
  163. meta_keyword: { type: string }
  164. meta_description: { type: string }
  165. img_pc: { type: string, nullable: true }
  166. yearList:
  167. type: array
  168. items: { type: string, example: '2026/07' }
  169. top: { $ref: '#/components/schemas/NewsListItem' }
  170. NewsParagraph:
  171. type: object
  172. oneOf:
  173. - type: object
  174. required: [type, content]
  175. properties:
  176. type: { type: string, enum: [text] }
  177. content: { type: string, description: HTML }
  178. - type: object
  179. required: [type, images]
  180. properties:
  181. type: { type: string, enum: [image] }
  182. images:
  183. type: array
  184. items:
  185. type: object
  186. properties:
  187. img_url: { type: string }
  188. alt: { type: string }
  189. - type: object
  190. required: [type, video_img_url, is_yt, content, video_url]
  191. properties:
  192. type: { type: string, enum: [video] }
  193. video_img_url: { type: string, nullable: true }
  194. is_yt: { type: boolean }
  195. content: { type: string }
  196. video_url: { type: string }
  197. DetailResponse:
  198. type: object
  199. properties:
  200. data:
  201. type: object
  202. properties:
  203. categoryId: { type: integer }
  204. category: { type: string }
  205. postDate: { type: string, example: '2015/05/06' }
  206. title: { type: string }
  207. description: { type: string }
  208. written: { type: string }
  209. img_pc: { type: string, nullable: true }
  210. img_mobile: { type: string, nullable: true }
  211. metaTitle: { type: string }
  212. metaKeyword: { type: string }
  213. metaDesc: { type: string }
  214. metaImg: { type: string, nullable: true }
  215. paragraphs:
  216. type: array
  217. items: { $ref: '#/components/schemas/NewsParagraph' }
  218. otherNews:
  219. type: object
  220. properties:
  221. previous: { $ref: '#/components/schemas/NewsListItem' }
  222. next: { $ref: '#/components/schemas/NewsListItem' }
  223. EsgMainResponse:
  224. type: object
  225. properties:
  226. data:
  227. type: object
  228. properties:
  229. meta:
  230. type: object
  231. properties:
  232. meta_title: { type: string }
  233. meta_keyword: { type: string }
  234. meta_description: { type: string }
  235. og_img: { type: string, nullable: true }
  236. img_pc: { type: string, nullable: true }
  237. img_mobile: { type: string, nullable: true }
  238. title: { type: string }
  239. description: { type: string }
  240. tab_list:
  241. type: array
  242. items:
  243. type: object
  244. properties:
  245. text: { type: string }
  246. key: { type: string }
  247. EsgParagraph:
  248. type: object
  249. oneOf:
  250. - type: object
  251. required: [type, content]
  252. properties:
  253. type: { type: string, enum: [text] }
  254. content: { type: string, description: HTML }
  255. - type: object
  256. required: [type, columns, content]
  257. properties:
  258. type: { type: string, enum: [grid] }
  259. columns: { type: integer }
  260. content:
  261. type: array
  262. items:
  263. type: object
  264. properties:
  265. type: { type: string, enum: [text] }
  266. content: { type: string }
  267. - type: object
  268. required: [type, is_card, header, body]
  269. properties:
  270. type: { type: string, enum: [table] }
  271. is_card: { type: boolean }
  272. header:
  273. type: array
  274. items:
  275. type: object
  276. properties:
  277. align: { type: integer }
  278. text: { type: string }
  279. body:
  280. type: array
  281. items:
  282. type: array
  283. items:
  284. type: object
  285. properties:
  286. align: { type: integer }
  287. text: { type: string }
  288. - type: object
  289. required: [type, images]
  290. properties:
  291. type: { type: string, enum: [image] }
  292. images:
  293. type: array
  294. items:
  295. type: object
  296. properties:
  297. image_url: { type: string }
  298. alt: { type: string }
  299. - type: object
  300. required: [type, is_yt, video_img_url, video_url, content]
  301. properties:
  302. type: { type: string, enum: [video] }
  303. is_yt: { type: boolean, example: true }
  304. video_img_url: { type: string }
  305. video_url: { type: string }
  306. content: { type: string }
  307. EsgContentResponse:
  308. type: object
  309. properties:
  310. data:
  311. type: object
  312. properties:
  313. banner:
  314. type: object
  315. properties:
  316. img_pc: { type: string, nullable: true }
  317. img_mobile: { type: string, nullable: true }
  318. img_alt: { type: string }
  319. text: { type: string }
  320. paragraphs:
  321. type: array
  322. items: { $ref: '#/components/schemas/EsgParagraph' }
  323. FailBody:
  324. type: object
  325. properties:
  326. status: { type: string, example: 'fail' }
  327. message: { type: string, example: '查無資料' }