openapi: 3.0.3 info: title: Yico 前台 API version: 1.0.0 description: | 對應 docs/api-spec.md。Base URL 實測 https://webdev.yico.tw:8088,path 前綴 /api。 全部 GET、免認證;{locale} 僅 tw|en;中文以 \uXXXX 跳脫;圖片 URL 含雙斜線。 servers: - url: https://webdev.yico.tw:8088/api description: staging(實測) - url: http://127.0.0.1:8083/api description: 本地 paths: /{locale}/news: get: summary: 置頂消息+年份清單 parameters: - $ref: '#/components/parameters/Locale' responses: '200': description: 成功;無置頂資料時回 [](空陣列) content: application/json: schema: oneOf: - $ref: '#/components/schemas/TopResponse' - type: array maxItems: 0 /{locale}/news/list: get: summary: 消息列表 parameters: - $ref: '#/components/parameters/Locale' - name: page in: query schema: { type: integer, default: 1 } - name: per_page in: query description: 每頁筆數;-1 取全部不分頁 schema: { type: integer, default: 15 } - name: year in: query schema: { type: integer } - name: month in: query description: 需與 year 並用,單獨傳入不過濾 schema: { type: integer } responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/ListResponse' /{locale}/news/detail/{id}: get: summary: 消息內文 parameters: - $ref: '#/components/parameters/Locale' - name: id in: path required: true schema: { type: integer } - name: preview in: query description: preview=1 時 bypass 可見性與有效期(免認證) schema: { type: string } responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/DetailResponse' '404': description: 不存在或未上架 content: application/json: schema: type: object properties: message: { type: string, example: 'news not found' } /{locale}/esg: get: summary: ESG 主視覺+頁籤 parameters: - $ref: '#/components/parameters/Locale' responses: '200': description: 成功;無 ESG 資料時缺 tab_list 鍵 content: application/json: schema: $ref: '#/components/schemas/EsgMainResponse' /{locale}/esg/{key}: get: summary: ESG 單頁內容 parameters: - $ref: '#/components/parameters/Locale' - name: key in: path required: true description: 頁籤 keyword(中文需 URL 編碼) schema: { type: string } responses: '200': description: '成功;查無資料時同為 200,body 為 {status: fail, message: 查無資料}' content: application/json: schema: oneOf: - $ref: '#/components/schemas/EsgContentResponse' - $ref: '#/components/schemas/FailBody' components: parameters: Locale: name: locale in: path required: true schema: type: string enum: [tw, en] schemas: Pagination: type: object properties: page: { type: string, example: '1' } per_page: { type: string, example: '2' } total: { type: integer } total_page: { type: integer } NewsListItem: type: object properties: id: { type: integer } categoryId: { type: integer } category: { type: string } postDate: { type: string, example: '2015.05.06' } title: { type: string } img_pc: { type: string, nullable: true } img_mobile: { type: string, nullable: true } written: { type: string } description: { type: string } ListResponse: type: object properties: data: type: object properties: pagination: { $ref: '#/components/schemas/Pagination' } list: type: array items: { $ref: '#/components/schemas/NewsListItem' } TopResponse: type: object properties: data: type: object properties: meta: type: object properties: meta_title: { type: string } meta_keyword: { type: string } meta_description: { type: string } img_pc: { type: string, nullable: true } yearList: type: array items: { type: string, example: '2026/07' } top: { $ref: '#/components/schemas/NewsListItem' } NewsParagraph: type: object oneOf: - type: object required: [type, content] properties: type: { type: string, enum: [text] } content: { type: string, description: HTML } - type: object required: [type, images] properties: type: { type: string, enum: [image] } images: type: array items: type: object properties: img_url: { type: string } alt: { type: string } - type: object required: [type, video_img_url, is_yt, content, video_url] properties: type: { type: string, enum: [video] } video_img_url: { type: string, nullable: true } is_yt: { type: boolean } content: { type: string } video_url: { type: string } DetailResponse: type: object properties: data: type: object properties: categoryId: { type: integer } category: { type: string } postDate: { type: string, example: '2015/05/06' } title: { type: string } description: { type: string } written: { type: string } img_pc: { type: string, nullable: true } img_mobile: { type: string, nullable: true } metaTitle: { type: string } metaKeyword: { type: string } metaDesc: { type: string } metaImg: { type: string, nullable: true } paragraphs: type: array items: { $ref: '#/components/schemas/NewsParagraph' } otherNews: type: object properties: previous: { $ref: '#/components/schemas/NewsListItem' } next: { $ref: '#/components/schemas/NewsListItem' } EsgMainResponse: type: object properties: data: type: object properties: meta: type: object properties: meta_title: { type: string } meta_keyword: { type: string } meta_description: { type: string } og_img: { type: string, nullable: true } img_pc: { type: string, nullable: true } img_mobile: { type: string, nullable: true } title: { type: string } description: { type: string } tab_list: type: array items: type: object properties: text: { type: string } key: { type: string } EsgParagraph: type: object oneOf: - type: object required: [type, content] properties: type: { type: string, enum: [text] } content: { type: string, description: HTML } - type: object required: [type, columns, content] properties: type: { type: string, enum: [grid] } columns: { type: integer } content: type: array items: type: object properties: type: { type: string, enum: [text] } content: { type: string } - type: object required: [type, is_card, header, body] properties: type: { type: string, enum: [table] } is_card: { type: boolean } header: type: array items: type: object properties: align: { type: integer } text: { type: string } body: type: array items: type: array items: type: object properties: align: { type: integer } text: { type: string } - type: object required: [type, images] properties: type: { type: string, enum: [image] } images: type: array items: type: object properties: image_url: { type: string } alt: { type: string } - type: object required: [type, is_yt, video_img_url, video_url, content] properties: type: { type: string, enum: [video] } is_yt: { type: boolean, example: true } video_img_url: { type: string } video_url: { type: string } content: { type: string } EsgContentResponse: type: object properties: data: type: object properties: banner: type: object properties: img_pc: { type: string, nullable: true } img_mobile: { type: string, nullable: true } img_alt: { type: string } text: { type: string } paragraphs: type: array items: { $ref: '#/components/schemas/EsgParagraph' } FailBody: type: object properties: status: { type: string, example: 'fail' } message: { type: string, example: '查無資料' }