Merge pull request #1522 from CVEProject/dr_1483_id_quota_documentation

Closes #1483 - id_quota documentation

Author: david-rocca

api-docs/openapi.json

@@ -2012,23 +2012,92 @@
     },
     "/registry/org/{shortname}/id_quota": {
       "get": {
-        "description": "",
+        "tags": [
+          "Registry Organization"
+        ],
+        "summary": "Retrieves an organization's CVE ID quota (accessible to all registered users)",
+        "description": "  <h2>Access Control</h2>  <p>All registered users can access this endpoint</p>  <h2>Expected Behavior</h2>  <p><b>Regular, CNA & Admin Users:</b> Retrieves the CVE ID quota for the user's organization</p>  <p><b>Secretariat:</b> Retrieves the CVE ID quota for any organization</p>",
+        "operationId": "orgIdQuota",
         "parameters": [
           {
             "name": "shortname",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string"
-            }
+            },
+            "description": "The shortname of the organization"
+          },
+          {
+            "$ref": "#/components/parameters/apiEntityHeader"
+          },
+          {
+            "$ref": "#/components/parameters/apiUserHeader"
+          },
+          {
+            "$ref": "#/components/parameters/apiSecretHeader"
           }
         ],
         "responses": {
+          "200": {
+            "description": "Returns the CVE ID quota for an organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/registry-org/get-registry-org-quota-response.json"
+                }
+              }
+            }
+          },
           "400": {
-            "description": "Bad Request"
+            "description": "Bad Request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/errors/bad-request.json"
+                }
+              }
+            }
           },
           "401": {
-            "description": "Unauthorized"
+            "description": "Not Authenticated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/errors/generic.json"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/errors/generic.json"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/errors/generic.json"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "../schemas/errors/generic.json"
+                }
+              }
+            }
           }
         }
       }

src/controller/org.controller/index.js

@@ -99,6 +99,73 @@ router.get('/registry/org/:shortname/users',
   controller.USER_ALL)
 
 router.get('/registry/org/:shortname/id_quota',
+  /*
+  #swagger.tags = ['Registry Organization']
+  #swagger.operationId = 'orgIdQuota'
+  #swagger.summary = "Retrieves an organization's CVE ID quota (accessible to all registered users)"
+  #swagger.description = "
+        <h2>Access Control</h2>
+        <p>All registered users can access this endpoint</p>
+        <h2>Expected Behavior</h2>
+        <p><b>Regular, CNA & Admin Users:</b> Retrieves the CVE ID quota for the user's organization</p>
+        <p><b>Secretariat:</b> Retrieves the CVE ID quota for any organization</p>"
+  #swagger.parameters['shortname'] = { description: 'The shortname of the organization' }
+  #swagger.parameters['$ref'] = [
+    '#/components/parameters/apiEntityHeader',
+    '#/components/parameters/apiUserHeader',
+    '#/components/parameters/apiSecretHeader'
+  ]
+  #swagger.responses[200] = {
+    description: 'Returns the CVE ID quota for an organization',
+    content: {
+      "application/json": {
+        schema: {
+          $ref: '../schemas/registry-org/get-registry-org-quota-response.json'
+        }
+      }
+    }
+  }
+  #swagger.responses[400] = {
+    description: 'Bad Request',
+    content: {
+      "application/json": {
+        schema: { $ref: '../schemas/errors/bad-request.json' }
+      }
+    }
+  }
+  #swagger.responses[401] = {
+    description: 'Not Authenticated',
+    content: {
+      "application/json": {
+        schema: { $ref: '../schemas/errors/generic.json' }
+      }
+    }
+  }
+  #swagger.responses[403] = {
+    description: 'Forbidden',
+    content: {
+      "application/json": {
+        schema: { $ref: '../schemas/errors/generic.json' }
+      }
+    }
+  }
+  #swagger.responses[404] = {
+    description: 'Not Found',
+    content: {
+      "application/json": {
+        schema: { $ref: '../schemas/errors/generic.json' }
+      }
+    }
+  }
+  #swagger.responses[500] = {
+    description: 'Internal Server Error',
+    content: {
+      "application/json": {
+        schema: { $ref: '../schemas/errors/generic.json' }
+      }
+    }
+  }
+  */
   mw.useRegistry(),
   mw.validateUser,
   param(['shortname']).isString().trim().notEmpty().isLength({ min: CONSTANTS.MIN_SHORTNAME_LENGTH, max: CONSTANTS.MAX_SHORTNAME_LENGTH }),