Add missing return data for most endpoints. Now requires #233

pulsar-edit · Jan 23, 2024 · c4a9a72 · c4a9a72
1 parent 93f3501
commit c4a9a72
Show file tree

Hide file tree

Showing 9 changed files with 93 additions and 10 deletions.
diff --git a/docs/swagger/openapi3_def.yaml b/docs/swagger/openapi3_def.yaml
@@ -17,12 +17,16 @@ paths:
   /api/login:
     get:
       summary: OAuth callback URL.
-      responses: {}
+      responses:
+        '302':
+          description: A redirect to the GitHub OAuth Authorization login flow.
       parameters: []
   /api/oauth:
     get:
       summary: OAuth Callback URL.
-      responses: {}
+      responses:
+        '302':
+          description: A redirect to the Pulsar Package Website User page.
       parameters: []
   /api/packages:
     post:
@@ -83,7 +87,10 @@ paths:
           description: >-
             Return a value similar to `GET /api/packages`, an array of package
             objects.
-          content: {}
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/packageObjectShortArray'
       parameters:
         - $ref: '#/components/parameters/auth'
   /api/themes:
@@ -150,14 +157,26 @@ paths:
   /api/packages/{packageName}/versions/{versionName}:
     get:
       summary: Get the details of a specific package version.
-      responses: {}
+      responses:
+        '200':
+          description: The 'package.json' plus more details of a single package version.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/packageObjectJSON'
       parameters:
         - $ref: '#/components/parameters/packageName'
         - $ref: '#/components/parameters/versionName'
   /api/themes/{packageName}/versions/{versionName}:
     get:
       summary: Get the details of a specific package version.
-      responses: {}
+      responses:
+        '200':
+          description: The 'package.json' plus more details of a single package version.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/packageObjectJSON'
       parameters:
         - $ref: '#/components/parameters/packageName'
         - $ref: '#/components/parameters/versionName'
@@ -234,13 +253,25 @@ paths:
   /api/packages/{packageName}/stargazers:
     get:
       summary: List the users that have starred a package.
-      responses: {}
+      responses:
+        '200':
+          description: A list of users.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/userObjectPublicArray'
       parameters:
         - $ref: '#/components/parameters/packageName'
   /api/themes/{packageName}/stargazers:
     get:
       summary: List the users that have starred a package.
-      responses: {}
+      responses:
+        '200':
+          description: A list of users.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/userObjectPublicArray'
       parameters:
         - $ref: '#/components/parameters/packageName'
   /api/packages/{packageName}/versions/{versionName}/events/uninstall:
@@ -277,7 +308,10 @@ paths:
       responses:
         '200':
           description: Return value is similar to `GET /api/packages`.
-          content: {}
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/packageObjectShortArray'
       parameters:
         - $ref: '#/components/parameters/login'
   /api/users/{login}:
@@ -631,3 +665,7 @@ components:
           type: string
         packages:
           type: array
+    userObjectPublicArray:
+      type: array
+      items:
+        $ref: '#/components/schemas/userObjectPublic'
diff --git a/src/controllers/deletePackagesPackageNameVersionsVersionName.js b/src/controllers/deletePackagesPackageNameVersionsVersionName.js
@@ -6,6 +6,11 @@ module.exports = {
   docs: {
     summary:
       "Deletes a package version. Once a version is deleted, it cannot be used again.",
+    responses: {
+      204: {
+        description: "An empty response, indicating success."
+      }
+    }
   },
   endpoint: {
     method: "DELETE",

diff --git a/src/controllers/getLogin.js b/src/controllers/getLogin.js
@@ -5,6 +5,11 @@
 module.exports = {
   docs: {
     summary: "OAuth callback URL.",
+    responses: {
+      302: {
+        description: "A redirect to the GitHub OAuth Authorization login flow."
+      }
+    }
   },
   endpoint: {
     method: "GET",

diff --git a/src/controllers/getOauth.js b/src/controllers/getOauth.js
@@ -7,6 +7,11 @@ const superagent = require("superagent");
 module.exports = {
   docs: {
     summary: "OAuth Callback URL.",
+    responses: {
+      302: {
+        description: "A redirect to the Pulsar Package Website User page."
+      }
+    }
   },
   endpoint: {
     method: "GET",

diff --git a/src/controllers/getPackagesPackageNameStargazers.js b/src/controllers/getPackagesPackageNameStargazers.js
@@ -5,6 +5,14 @@
 module.exports = {
   docs: {
     summary: "List the users that have starred a package.",
+    responses: {
+      200: {
+        description: "A list of users.",
+        content: {
+          "application/json": "$userObjectPublicArray"
+        }
+      }
+    }
   },
   endpoint: {
     method: "GET",

diff --git a/src/controllers/getPackagesPackageNameVersionsVersionName.js b/src/controllers/getPackagesPackageNameVersionsVersionName.js
@@ -5,6 +5,14 @@
 module.exports = {
   docs: {
     summary: "Get the details of a specific package version.",
+    responses: {
+      200: {
+        description: "The 'package.json' plus more details of a single package version.",
+        content: {
+          "application/json": "$packageObjectJSON"
+        }
+      }
+    }
   },
   endpoint: {
     method: "GET",

diff --git a/src/controllers/getStars.js b/src/controllers/getStars.js
@@ -9,7 +9,9 @@ module.exports = {
       200: {
         description:
           "Return a value similar to `GET /api/packages`, an array of package objects.",
-        content: {},
+        content: {
+          "application/json": "$packageObjectShortArray"
+        },
       },
     },
   },

diff --git a/src/controllers/getUsersLoginStars.js b/src/controllers/getUsersLoginStars.js
@@ -8,7 +8,9 @@ module.exports = {
     responses: {
       200: {
         description: "Return value is similar to `GET /api/packages`.",
-        content: {},
+        content: {
+          "application/json": "$packageObjectShortArray"
+        },
       },
     },
   },

diff --git a/tests/models/userObjectPublicArray.js b/tests/models/userObjectPublicArray.js
@@ -0,0 +1,10 @@
+module.exports = {
+  schema: {
+    type: "array",
+    items: {
+      "$ref": "#/components/schemas/userObjectPublic"
+    }
+  },
+  example: [require("./userObjectPublic.js").example],
+  test: Joi.array().items(require("./userObjectPublic.js").test).required()
+};