Document endpoint /api/player/autocomplete (fix #847) (#848)

* Document endpoint /api/player/autocomplete (fix #847) * Move endpoint to /api/player/autocomplete
WandererXII · Jul 15, 2024 · 11f9451 · 11f9451
1 parent fea7739
commit 11f9451
Show file tree

Hide file tree

Showing 7 changed files with 66 additions and 9 deletions.
diff --git a/conf/routes b/conf/routes
@@ -57,7 +57,7 @@ GET   /player                          controllers.User.list
 GET   /player/top/:nb/:perfKey         controllers.User.topNb(nb: Int, perfKey: String)
 GET   /player/top/week                 controllers.User.topWeek
 GET   /player/online                   controllers.User.online
-GET   /player/autocomplete             controllers.User.autocomplete
+GET   /api/player/autocomplete         controllers.User.autocomplete
 
 GET   /dasher                          controllers.Dasher.get
 

diff --git a/public/doc/lishogi-api.yaml b/public/doc/lishogi-api.yaml
@@ -2364,6 +2364,60 @@ paths:
               schema:
                 $ref: '#/components/schemas/Crosstable'
 
+  /api/player/autocomplete:
+    get:
+      operationId: apiPlayerAutocomplete
+      summary: Autocomplete usernames
+      description: |
+        Provides autocompletion options for an incomplete username.
+      tags:
+        - Users
+      security: []
+      parameters:
+        - in: query
+          name: term
+          description: The beginning of a username
+          schema:
+            type: string
+            minLength: 3
+          required: true
+        - in: query
+          name: object
+          description: |
+            - `false` returns an array of usernames
+            - `true` returns an object with matching users
+          schema:
+            type: boolean
+            default: false
+        - in: query
+          name: friend
+          description: |
+            Returns followed players matching `term` if any, else returns other players.
+            Requires [OAuth](#tag/OAuth).
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: An array of players which usernames start with the provided term.
+          headers:
+            Access-Control-Allow-Origin:
+              schema:
+                type: string
+                default: "'*'"
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - type: array
+                    items:
+                      type: string
+                  - type: object
+                    properties:
+                      result:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/LightUser'
+
   /api/stream/event:
     get:
       operationId: apiStreamEvent
@@ -4328,6 +4382,9 @@ components:
     LightUser:
       type: object
       properties:
+        id:
+          type: string
+          example: "shogi_harbour"
         name:
           type: string
           example: "Shogi_Harbour"
@@ -4338,9 +4395,9 @@ components:
         patron:
           type: boolean
           example: true
-        id:
-          type: string
-          example: "shogi_harbour"
+        online:
+          type: boolean
+          example: true
 
     Perf:
       type: object

diff --git a/public/javascripts/forum-post.js b/public/javascripts/forum-post.js
@@ -62,7 +62,7 @@ $(function () {
                     // We fall back to every site user after 3 letters of the username have been entered
                     // and there are no matches in the forum thread participants
                     $.ajax({
-                      url: '/player/autocomplete',
+                      url: '/api/player/autocomplete',
                       data: {
                         term: term,
                       },

diff --git a/public/javascripts/signup.js b/public/javascripts/signup.js
@@ -7,7 +7,7 @@ $(function () {
     if (name.length >= 3)
       $.ajax({
         method: 'GET',
-        url: '/player/autocomplete',
+        url: '/api/player/autocomplete',
         data: {
           term: name,
           exists: 1,

diff --git a/public/javascripts/team-admin.js b/public/javascripts/team-admin.js
@@ -16,7 +16,7 @@ $(() => {
     // show loading animation and hide the suggestions dropdown
     tagify.loading(true).dropdown.hide.call(tagify);
 
-    fetch(`/player/autocomplete?term=${encodeURIComponent(term)}&names=1`, {
+    fetch(`/api/player/autocomplete?term=${encodeURIComponent(term)}&names=1`, {
       signal: abortCtrl.signal,
     })
       .then(r => r.json())

diff --git a/ui/site/src/clas.js b/ui/site/src/clas.js
@@ -35,7 +35,7 @@ $(function () {
             if (term.length < 2) callback([]);
             else
               $.ajax({
-                url: '/player/autocomplete?object=1&teacher=1',
+                url: '/api/player/autocomplete?object=1&teacher=1',
                 data: {
                   term: term,
                 },

diff --git a/ui/site/src/main.js b/ui/site/src/main.js
@@ -173,7 +173,7 @@
             source: function (query, _, runAsync) {
               if (query.trim().match(/^[a-z0-9][\w-]{2,29}$/i))
                 $.ajax({
-                  url: '/player/autocomplete',
+                  url: '/api/player/autocomplete',
                   cache: true,
                   data: {
                     term: query,