347 lines
9.0 KiB
YAML
347 lines
9.0 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Discord MemeBot API
|
||
description: >
|
||
Go Final Project 後端 API 文件。
|
||
包含圖片上傳、檢索、Alias 管理以及 Discord OAuth 認證流程。
|
||
version: 1.0.0
|
||
|
||
servers:
|
||
- url: http://localhost:8080
|
||
description: 本地開發伺服器
|
||
|
||
# 定義 Tag 的順序與描述 (讓文件更漂亮)
|
||
tags:
|
||
- name: Image
|
||
description: 圖片相關操作 (查詢、上傳、刪除、取得檔案)
|
||
- name: Alias
|
||
description: 全域 Alias 列表
|
||
- name: Linking/Unlinking
|
||
description: 圖片與 Alias 之間的關聯管理
|
||
- name: Authentication
|
||
description: 使用者身分驗證與 Token 交換
|
||
|
||
# 全域安全驗證
|
||
security:
|
||
- bearerAuth: []
|
||
|
||
paths:
|
||
# ----------------------------------------------------------------
|
||
# Image (圖片資源)
|
||
# ----------------------------------------------------------------
|
||
/api/images:
|
||
get:
|
||
tags:
|
||
- Image
|
||
summary: 取得圖片列表
|
||
description: 列出圖片，支援關鍵字搜尋、分頁與無 Alias 過濾。
|
||
parameters:
|
||
- name: search
|
||
in: query
|
||
description: 搜尋 Alias 關鍵字 (模糊搜尋)
|
||
schema:
|
||
type: string
|
||
- name: null_alias
|
||
in: query
|
||
description: 若為 true，只回傳沒有任何 alias 的圖片
|
||
schema:
|
||
type: boolean
|
||
- name: limit
|
||
in: query
|
||
description: 分頁：每頁幾筆
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
- name: page
|
||
in: query
|
||
description: 分頁：第幾頁
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
responses:
|
||
'200':
|
||
description: 成功取得列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
images:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Image'
|
||
|
||
post:
|
||
tags:
|
||
- Image
|
||
summary: 上傳圖片
|
||
description: 上傳圖片並設定初始 aliases。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
imgfile:
|
||
type: string
|
||
format: binary
|
||
description: 圖片檔案
|
||
aliases:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: 初始 Alias 列表 (支援重複 key 傳送)
|
||
required:
|
||
- imgfile
|
||
responses:
|
||
'201':
|
||
description: 圖片建立成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Image'
|
||
|
||
/api/images/{id}:
|
||
get:
|
||
tags:
|
||
- Image
|
||
summary: 取得單張圖片資訊 (Metadata)
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Image'
|
||
|
||
delete:
|
||
tags:
|
||
- Image
|
||
summary: 刪除圖片
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'204':
|
||
description: 刪除成功 (No Content)
|
||
|
||
/api/images/{id}/file:
|
||
get:
|
||
tags:
|
||
- Image
|
||
summary: 取得圖片原始檔案 (Binary)
|
||
description: 用於 <img src="...">
|
||
security: [] # 若圖片公開可留空
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: 圖片串流
|
||
content:
|
||
image/png:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
image/jpeg:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
image/gif:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
|
||
# ----------------------------------------------------------------
|
||
# Alias (全域列表)
|
||
# ----------------------------------------------------------------
|
||
/api/aliases:
|
||
get:
|
||
tags:
|
||
- Alias
|
||
summary: 取得所有 Alias
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
aliases:
|
||
type: array
|
||
items:
|
||
type: string
|
||
example: ["114514", "哼哼啊啊啊啊", "poop"]
|
||
|
||
# ----------------------------------------------------------------
|
||
# Linking/Unlinking (關聯管理)
|
||
# ----------------------------------------------------------------
|
||
/api/images/{id}/aliases:
|
||
post:
|
||
tags:
|
||
- Linking/Unlinking
|
||
summary: 新增單一 Alias (關聯)
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
alias:
|
||
type: string
|
||
example: "先輩"
|
||
responses:
|
||
'200':
|
||
description: 新增成功，回傳更新後的圖片資訊
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Image'
|
||
|
||
delete:
|
||
tags:
|
||
- Linking/Unlinking
|
||
summary: 刪除單一 Alias (關聯)
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: alias
|
||
in: query
|
||
description: 要刪除的 alias 文字
|
||
required: true
|
||
schema:
|
||
type: string
|
||
example: "先輩"
|
||
responses:
|
||
'204':
|
||
description: 刪除成功 (No Content)
|
||
|
||
put:
|
||
tags:
|
||
- Linking/Unlinking
|
||
summary: 批次取代 Alias 列表
|
||
description: 用於前端編輯視窗的 Save 功能，完全取代舊有列表。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
aliases:
|
||
type: array
|
||
items:
|
||
type: string
|
||
example: ["先輩", "好時代", "114514"]
|
||
responses:
|
||
'200':
|
||
description: 更新成功，回傳更新後的圖片資訊
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Image'
|
||
|
||
# ----------------------------------------------------------------
|
||
# Authentication (驗證)
|
||
# ----------------------------------------------------------------
|
||
/auth/gen-access-url:
|
||
post:
|
||
tags:
|
||
- Authentication
|
||
summary: JWT 交換 (Login)
|
||
description: 使用 Discord OAuth Code 交換 Access Token
|
||
security: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: Discord OAuth Code
|
||
redirect_uri:
|
||
type: string
|
||
grant_type:
|
||
type: string
|
||
default: authorization_code
|
||
required:
|
||
- code
|
||
responses:
|
||
'200':
|
||
description: 登入成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
access_token:
|
||
type: string
|
||
token_type:
|
||
type: string
|
||
example: "Bearer"
|
||
expires_in:
|
||
type: integer
|
||
example: 3600
|
||
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
|
||
schemas:
|
||
Image:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
example: "101"
|
||
uploaded_user_id:
|
||
type: string
|
||
example: "konchin.shih"
|
||
uploaded_at:
|
||
type: string
|
||
format: date-time
|
||
example: "2023-10-20T12:00:00Z"
|
||
aliases:
|
||
type: array
|
||
items:
|
||
type: string
|
||
example: ["野獸", "先輩", "114514"]
|
||
url:
|
||
type: string
|
||
description: 圖片二進制檔案的 API 路徑
|
||
example: "/api/images/101/file" |