feat: add api spec for subjects browsing

bangumi · May 25, 2024 · 303bb02 · 303bb02
1 parent a2dd226
commit 303bb02
Show file tree

Hide file tree

Showing 9 changed files with 276 additions and 7 deletions.
diff --git a/Taskfile.yaml b/Taskfile.yaml
@@ -44,6 +44,31 @@ tasks:
     env:
       CGO_ENABLED: "0"
 
+  web:
+    desc: Run Web Server
+    aliases:
+      - serve
+      - server
+    cmds:
+      - go run main.go --config config.yaml web
+
+  consumer:
+    desc: Run Kafka Consumer
+    aliases:
+      - canal
+    cmds:
+      - go run main.go canal --config config.yaml
+
+  openapi-test:
+    desc: Test OpenAPI Schema
+    cmds:
+      - npm run test
+
+  openapi:
+    desc: Build OpenAPI Schema
+    cmds:
+      - npm run build
+
   bench:
     desc: Run benchmark
     cmds:

diff --git a/openapi/components/subject_cat_anime.yaml b/openapi/components/subject_cat_anime.yaml
@@ -0,0 +1,31 @@
+title: SubjectAnimeCategory
+example: 1
+enum:
+  - 0
+  - 1
+  - 2
+  - 3
+  - 5
+type: integer
+description: |-
+  动画类型
+  - `0` 为 其他
+  - `1` 为 TV
+  - `2` 为 OVA
+  - `3` 为 Movie
+  - `5` 为 WEB
+x-ms-enum:
+  name: SubjectAnimeCategory
+  modelAsString: false
+  values:
+    - Other
+    - TV
+    - OVA
+    - Movie
+    - WEB
+x-enum-varnames:
+  - Other
+  - TV
+  - OVA
+  - Movie
+  - WEB
diff --git a/openapi/components/subject_cat_book.yaml b/openapi/components/subject_cat_book.yaml
@@ -0,0 +1,27 @@
+title: SubjectBookCategory
+example: 1001
+enum:
+  - 0
+  - 1001
+  - 1002
+  - 1003
+type: integer
+description: |-
+  书籍类型
+  - `0` 为 其他
+  - `1001` 为 漫画
+  - `1002` 为 小说
+  - `1003` 为 画集
+x-ms-enum:
+  name: SubjectBookCategory
+  modelAsString: false
+  values:
+    - Other
+    - Comic
+    - Novel
+    - Illustration
+x-enum-varnames:
+  - Other
+  - Comic
+  - Novel
+  - Illustration
diff --git a/openapi/components/subject_cat_game.yaml b/openapi/components/subject_cat_game.yaml
@@ -0,0 +1,31 @@
+title: SubjectGameCategory
+example: 4001
+enum:
+  - 0
+  - 4001
+  - 4003
+  - 4002
+  - 4005
+type: integer
+description: |-
+  游戏类型
+  - `0` 为 其他
+  - `4001` 为 游戏
+  - `4002` 为 软件
+  - `4003` 为 扩展包
+  - `4005` 为 桌游
+x-ms-enum:
+  name: SubjectGameCategory
+  modelAsString: false
+  values:
+    - Other
+    - Games
+    - Software
+    - DLC
+    - Tabletop
+x-enum-varnames:
+  - Other
+  - Games
+  - Software
+  - DLC
+  - Tabletop
diff --git a/openapi/components/subject_cat_real.yaml b/openapi/components/subject_cat_real.yaml
@@ -0,0 +1,43 @@
+title: SubjectRealCategory
+example: 6
+enum:
+  - 0
+  - 1
+  - 2
+  - 3
+  - 6001
+  - 6002
+  - 6003
+  - 6004
+type: integer
+description: |-
+  电影类型
+  - `0` 为 其他
+  - `1` 为 日剧
+  - `2` 为 欧美剧
+  - `3` 为 华语剧
+  - `6001` 为 电视剧
+  - `6002` 为 电影
+  - `6003` 为 演出
+  - `6004` 为 综艺
+x-ms-enum:
+  name: SubjectRealCategory
+  modelAsString: false
+  values:
+    - Other
+    - JP
+    - EN
+    - CN
+    - TV
+    - Movie
+    - Live
+    - Show
+x-enum-varnames:
+  - Other
+  - JP
+  - EN
+  - CN
+  - TV
+  - Movie
+  - Live
+  - Show
diff --git a/openapi/components/subject_v0.yaml b/openapi/components/subject_v0.yaml
@@ -47,7 +47,7 @@ properties:
   platform:
     title: Platform
     type: string
-    description: TV, Web, 欧美剧, PS4...
+    description: TV, Web, 欧美剧, DLC...
   images:
     $ref: "./subject_image.yaml"
   infobox:

diff --git a/openapi/components/subject_v0_slim.yaml b/openapi/components/subject_v0_slim.yaml
@@ -52,8 +52,12 @@ properties:
     type: integer
   score:
     description: 分数
-    title: Total
+    title: Score
     type: number
+  rank:
+    description: 排名
+    title: Rank
+    type: integer
 
   tags:
     description: 前 10 个 tag

diff --git a/openapi/v0.yaml b/openapi/v0.yaml
@@ -196,6 +196,80 @@ paths:
                           description: 排名
                           "type": "integer"
 
+  "/v0/subjects":
+    get:
+      tags:
+        - 条目
+      summary: 浏览条目
+      operationId: getSubjects
+      parameters:
+        - name: type
+          in: query
+          description: 条目类型
+          required: true
+          schema:
+            $ref: "#/components/schemas/SubjectType"
+        - name: cat
+          in: query
+          description: 条目分类，参照 `SubjectCategory` enum
+          required: false
+          schema:
+            $ref: "#/components/schemas/SubjectCategory"
+        - name: series
+          in: query
+          description: 是否系列，仅对书籍类型的条目有效
+          required: false
+          schema:
+            type: boolean
+        - name: platform
+          in: query
+          description: 平台，仅对游戏类型的条目有效
+          required: false
+          schema:
+            type: string
+        - name: order
+          in: query
+          description: 排序，枚举值 {date|rank}
+          required: false
+          schema:
+            title: Sort Order
+            type: string
+        - name: year
+          in: query
+          description: 年份
+          required: false
+          schema:
+            type: integer
+        - name: month
+          in: query
+          description: 月份
+          required: false
+          schema:
+            type: integer
+        - $ref: "#/components/parameters/default_query_limit"
+        - $ref: "#/components/parameters/default_query_offset"
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Paged_Subject"
+        "400":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorDetail"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorDetail"
+      security:
+        - OptionalHTTPBearer: []
+
   "/v0/subjects/{subject_id}":
     get:
       tags:
@@ -2310,9 +2384,7 @@ components:
           title: ID
           type: integer
         type:
-          title: Type
-          type: integer
-          description: "`0` 本篇，`1` SP，`2` OP，`3` ED"
+          $ref: "#/components/schemas/EpType"
         name:
           title: Name
           type: string
@@ -2481,6 +2553,28 @@ components:
     Page:
       $ref: "./components/page.yaml"
 
+    Paged_Subject:
+      title: Paged[Subject]
+      type: object
+      properties:
+        total:
+          title: Total
+          type: integer
+          default: 0
+        limit:
+          title: Limit
+          type: integer
+          default: 0
+        offset:
+          title: Offset
+          type: integer
+          default: 0
+        data:
+          title: Data
+          type: array
+          items:
+            "$ref": "#/components/schemas/Subject"
+          default: []
     Paged_Episode:
       title: Paged[Episode]
       type: object
@@ -3002,6 +3096,20 @@ components:
       $ref: "./components/subject_tags.yaml"
     SubjectType:
       $ref: "./components/subject_type.yaml"
+    SubjectBookCategory:
+      $ref: "./components/subject_cat_book.yaml"
+    SubjectAnimeCategory:
+      $ref: "./components/subject_cat_anime.yaml"
+    SubjectGameCategory:
+      $ref: "./components/subject_cat_game.yaml"
+    SubjectRealCategory:
+      $ref: "./components/subject_cat_real.yaml"
+    SubjectCategory:
+      anyOf:
+        - $ref: "#/components/schemas/SubjectBookCategory"
+        - $ref: "#/components/schemas/SubjectAnimeCategory"
+        - $ref: "#/components/schemas/SubjectGameCategory"
+        - $ref: "#/components/schemas/SubjectRealCategory"
     UserSubjectCollection:
       $ref: "./components/user_subject_collection.yaml"
     UserSubjectCollectionModifyPayload:

diff --git a/readme.md b/readme.md
@@ -78,13 +78,13 @@ ORM: [GORM](https://github.com/go-gorm/gorm) 和 [GORM Gen](https://github.com/g
 启动 HTTP server
 
 ```shell
-go run main.go --config config.yaml web
+task web
 ```
 
 启动 kafka consumer
 
 ```shell
-go run main.go canal --config config.yaml
+task consumer
 ```
 
 ### 后端环境