| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328 |
- 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: '查無資料' }
|