Merge pull request #24 from chhsiao1981/apidoc-3

adding board-users, title, name, desc, limit in apidoc

api/get_article_detail.go

@@ -25,7 +25,7 @@ type GetArticleDetailResult struct {
 	Brdname string        `json:"brdname"`
 	Content proto.Content `json:"content"`
 	IP      string        `json:"ip"`
-	Country string        `json:"country"`
+	Host    string        `json:"host"` //ip 的中文呈現, 外國則為國家.
 	BBS     string        `json:"bbs"`
 }
 

api/get_user_info.go

@@ -29,8 +29,8 @@ type GetUserInfoResult struct {
 	Numposts     int           `json:"posts"`
 	Firstlogin   types.Time8   `json:"first_login"`
 	Lastlogin    types.Time8   `json:"last_login"`
-	Lasthost     string        `json:"last_ip"`
-	Country      string        `json:"country"`
+	LastIP       string        `json:"last_ip"`
+	LastHost     string        `json:"last_host"` //ip 的中文呈現, 外國則為國家.
 
 	Money   int    `json:"money"`
 	Email   string `json:"email"`
@@ -95,7 +95,7 @@ func GetUserInfo(remoteAddr string, userID bbs.UUserID, params interface{}, path
 		Numposts:     123124,
 		Firstlogin:   types.Time8(1234567890),
 		Lastlogin:    types.Time8(1800000000),
-		Lasthost:     "127.0.0.1",
+		LastIP:       "127.0.0.1",
 		Money:        2114567890,
 
 		Email:     "[email protected]",

apidoc/apidoc.py

@@ -97,6 +97,15 @@ def _get_user_info(user_id):
     return ''
 
 
+@app.route(_with_app_prefix('/user/<user_id>/summary'))
+def _get_user_summary(user_id):
+    """
+    swagger_from_file: apidoc/get_user_summary.yaml
+
+    """
+    return ''
+
+
 @app.route(_with_app_prefix('/user/<user_id>/articles'))
 def _load_user_articles(user_id):
     """
@@ -181,3 +190,12 @@ def _get_board_summary(bid):
 
     """
     return ''
+
+
+@app.route(_with_app_prefix('/board/<bid>/users'))
+def _get_board_users(bid):
+    """
+    swagger_from_file: apidoc/load_board_users.yaml
+
+    """
+    return ''

apidoc/defs/article_detail_core.yaml

@@ -7,9 +7,9 @@ content:
 ip:
   type: string
   description: 作者 ip.
-country:
+host:
   type: string
-  description: ip 的國家.
+  description: ip 的中文呈現, 外國則為國家.
 bbs:
   type: string
   description: 發信站.

apidoc/defs/board_detail_fail_core.yaml

@@ -1,7 +1,7 @@
 moderators:
   type: array
   items:
-    '$ref': '#/definitions/UID'
+    '$ref': '#/definitions/user_id'
 reason:
   type: string
   description: 不給看的原因.

apidoc/defs/comment_list.yaml

@@ -8,4 +8,3 @@ CommentList:
         '$ref': '#/definitions/Comment'
     nextIdx:
       '$ref': '#/definitions/RespNextIdx'
-

apidoc/defs/params_desc.yaml

@@ -0,0 +1,7 @@
+ParamsDesc:
+  name: 'desc'
+  in: 'query'
+  required: false
+  description: "descending or ascending"
+  type: boolean
+  default: true

apidoc/defs/params_max.yaml

@@ -1,5 +1,5 @@
-ParamsMax:
-  name: 'max'
+ParamsLimit:
+  name: 'limit'
   in: 'query'
   required: false
   description: "max number of the returned list, requiring <= 300"

apidoc/defs/uid.yaml

@@ -1,3 +1,3 @@
 user_id:
   type: string
-  description: username
+  description: user_id

apidoc/defs/uid_core.yaml

@@ -0,0 +1 @@
+'$ref': '#/definitions/user_id'

apidoc/defs/user_detail.yaml

@@ -2,5 +2,6 @@ UserDetail:
   type: object
   properties:
     !include uid.yaml
+    !include username_core.yaml
     !include nickname_core.yaml
     !include user_detail_core.yaml

apidoc/defs/user_detail_core.yaml

@@ -20,14 +20,24 @@ last_login:
 last_ip:
   type: string
   description: from-ip
-country:
+last_host:
   type: string
-  description: last_ip 的國家.
+  description: last_ip 的網域.
 
 money:
   type: number
 email:
   type: string
+email_verified:
+  type: string
+phone:
+  type: string
+phone_verified:
+  type: string
+twofactor_enabled:
+  type: boolean
+justify:
+  type: string
 address:
   type: string
 over18:
@@ -52,6 +62,10 @@ role:
 last_seen:
   type: number
   description: last-seen in unix-time
+last_action:
+  type: string
+last_action_time:
+  type: number
 time_set_angel:
   type: number
 time_play_angel:

apidoc/defs/user_list.yaml

@@ -0,0 +1,9 @@
+UserList:
+  type: object
+  properties:
+    list:
+      type: array
+      items:
+        '$ref': '#/definitions/UserListSummary'
+    nextIdx:
+      '$ref': '#/definitions/RespNextIdx'

apidoc/defs/user_list_summary.yaml

@@ -0,0 +1,7 @@
+UserListSummary:
+  type: object
+  properties:
+    !include uid_core.yaml
+    !include username_core.yaml
+    !include nickname_core.yaml
+    !include user_list_summary_core.yaml

apidoc/defs/user_list_summary_core.yaml

@@ -0,0 +1,13 @@
+last_ip:
+  type: string
+  description: from-ip
+last_host:
+  type: string
+  description: last_ip 的網域.
+last_action:
+  type: string
+last_action_time:
+  type: number
+pager:
+  type: number
+  description: https://github.com/Ptt-official-app/go-pttbbs/blob/main/ptttype/modes.go#L5

apidoc/defs/user_summary.yaml

@@ -0,0 +1,7 @@
+UserSummary:
+  type: object
+  properties:
+    !include uid_core.yaml
+    !include username_core.yaml
+    !include nickname_core.yaml
+    !include user_summary_core.yaml

apidoc/defs/user_summary_core.yaml

@@ -0,0 +1,65 @@
+login_days:
+  type: number
+post:
+  type: number
+last_action:
+  type: string
+last_action_time:
+  type: number
+last_login:
+  type: number
+  description: last-login in unix-time
+badpost:
+  type: number
+  description: badpost count
+money:
+  type: number
+
+five_win:
+  type: number
+  description: 五子棋(贏)
+five_lose:
+  type: number
+  description: 五子棋(輸)
+five_tie:
+  type: number
+  description: 五子棋(平)
+chc_win:
+  type: number
+  description: 象棋(贏)
+chc_lose:
+  type: number
+  description: 象棋(輸)
+chc_tie:
+  type: number
+  description: 象棋(平)
+conn6_win:
+  type: number
+  description: 六子棋(贏)
+conn6_lose:
+  type: number
+  description: 六子棋(輸)
+conn6_tie:
+  type: number
+  description: 六子棋(平)
+go_win:
+  type: number
+  description: 圍棋(贏)
+go_lose:
+  type: number
+  description: 圍棋(輸)
+go_tie:
+  type: number
+  description: 圍棋(平)
+dark_win:
+  type: number
+  description: 暗棋(贏)
+dark_lose:
+  type: number
+  description: 暗棋(輸)
+dark_tie:
+  type: number
+  description: 暗棋(平)
+chess_rank:
+  type: number
+  description: 象棋等級

apidoc/defs/username_core.yaml

@@ -0,0 +1,2 @@
+username:
+  type: string

apidoc/get_user_info.yaml

@@ -1,4 +1,4 @@
-GetUserInfo
+拿到本人的所有資訊.
 ---
 tags:
   - user

apidoc/get_user_summary.yaml

@@ -0,0 +1,17 @@
+拿到 user 的 summary 資訊.
+---
+tags:
+  - user
+definitions:
+parameters:
+  - name: 'user_id'
+    in: 'path'
+    required: true
+    type: string
+  - '$ref': '#/definitions/ParamsFields'
+responses:
+  200:
+    description:
+    schema:
+      '$id': https://json-schema.org/draft/2019-09/output/schema
+      '$ref': '#/definitions/UserSummary'

apidoc/load_article_comments.yaml

@@ -3,7 +3,7 @@
 tags:
   - article
   - comment
-description: get user comment list, sorted by time. (from newest to oldest).
+description: get user comment list, sorted by time.
 parameters:
   - '$ref': '#/definitions/ParamsAuthorization'
   - name: 'bid'
@@ -15,7 +15,8 @@ parameters:
     type: string
     required: true
   - '$ref': '#/definitions/ParamsStartIdx'
-  - '$ref': '#/definitions/ParamsMax'
+  - '$ref': '#/definitions/ParamsLimit'
+  - '$ref': '#/definitions/ParamsDesc'
 responses:
   200:
     description:

apidoc/load_article_firstcomments.yaml

@@ -1,9 +1,9 @@
-讀取文章裡一開始的 comments (從最舊往最新拉資料. 舊的排在前面.)
+讀取文章裡置頂 comments
 ---
 tags:
   - article
   - comment
-description: get user comment list, sorted by time. (from newest to oldest).
+description: 讀置頂 comments.
 parameters:
   - '$ref': '#/definitions/ParamsAuthorization'
   - name: 'bid'
@@ -14,8 +14,6 @@ parameters:
     in: 'path'
     type: string
     required: true
-  - '$ref': '#/definitions/ParamsStartIdx'
-  - '$ref': '#/definitions/ParamsMax'
 responses:
   200:
     description:

apidoc/load_board_users.yaml

@@ -0,0 +1,28 @@
+讀取板的上線板友名單
+---
+tags:
+  - board
+  - user
+description: 讀取板的上線板友名單
+parameters:
+  - '$ref': '#/definitions/ParamsAuthorization'
+  - name: 'bid'
+    in: 'path'
+    required: true
+    description: "board bid obtained from board-list"
+    type: string
+  - name: 'name'
+    in: 'query'
+    required: false
+    description: "query string, '' returns all users"
+    type: string
+    default: ''
+  - '$ref': '#/definitions/ParamsStartIdx'
+  - '$ref': '#/definitions/ParamsLimit'
+  - '$ref': '#/definitions/ParamsDesc'
+responses:
+  200:
+    description:
+    schema:
+      '$id': https://json-schema.org/draft/2019-09/output/schema
+      '$ref': '#/definitions/UserList'

apidoc/load_favorite_boards.yaml

@@ -16,7 +16,8 @@ parameters:
     default: ''
     description: 以 , 隔開指示我的最愛的層數. '' 表示 root 層
   - '$ref': '#/definitions/ParamsStartIdx'
-  - '$ref': '#/definitions/ParamsMax'
+  - '$ref': '#/definitions/ParamsLimit'
+  - '$ref': '#/definitions/ParamsDesc'
 responses:
   200:
     description:

apidoc/load_general_articles.yaml

@@ -3,16 +3,23 @@
 tags:
   - board
   - article
-description: 讀取板裡的文章列表 (按照時間排序. 從最新開始往以前拿取. 呈現時舊的排前面.)
+description: 讀取板裡的文章列表, 呈現時舊的排前面.
 parameters:
   - '$ref': '#/definitions/ParamsAuthorization'
   - name: 'bid'
     in: 'path'
     required: true
     description: "board bid obtained from board-list"
     type: string
+  - name: 'title'
+    in: 'query'
+    required: false
+    description: "query string, '' returns all articles"
+    type: string
+    default: ''
   - '$ref': '#/definitions/ParamsStartIdx'
-  - '$ref': '#/definitions/ParamsMax'
+  - '$ref': '#/definitions/ParamsLimit'
+  - '$ref': '#/definitions/ParamsDesc'
 responses:
   200:
     description: