Merge pull request #7056 from BenJamesBen/apikeys-list-doc

fix(docs): Add/update API keys list
freesewing · Oct 26, 2024 · d798ec8 · d798ec8
2 parents 2d7b4d4 + fcc5214
commit d798ec8
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 9 deletions.
diff --git a/markdown/dev/reference/backend/apikeys/list/en.md b/markdown/dev/reference/backend/apikeys/list/en.md
@@ -0,0 +1,62 @@
+---
+title: List API keys
+---
+
+Lists existing API keys.
+
+## Access control
+
+- [Permission level](/reference/backend/rbac) `0` or higher is required to list API keys
+
+## Endpoints
+
+Listing API keys is possible via these endpoints:
+
+| Method    | Path | Authentication |
+| --------: | :--- | :------------- |
+| <Method get /> | `/apikeys/jwt` | [JSON Web Token](/reference/backend/authentication#jwt-authentication) |
+| <Method get /> | `/apikeys/key` | [API Key & Secret](/reference/backend/authentication#key-authentication) |
+
+## Response status codes
+
+Possible status codes for these endpoints are:
+
+| Status code | Description |
+| ----------: | :---------- |
+| <StatusCode status="200"/> | success |
+| <StatusCode status="404"/> | API key not found |
+
+## Response body
+
+| Value               | Type     | Description |
+| ------------------- | -------- | ----------- |
+| `result`            | `string` | `success` on success, and `error` on error |
+| `error`             | `string` | Will give info on the nature of the error. Only set if an error occurred. |
+| `apikeys`           | `Array`` | Array of API key strings |
+
+## Example request
+
+```js
+const keyInfo = await axios.get(
+  'https://backend.freesewing.org/apikeys/jwt',
+  {
+    headers: {
+      Authorization: `Bearer ${token}`
+    }
+  }
+)
+```
+
+## Example response
+```200.json
+{
+  "result": "success",
+  "apikeys": {
+    [
+      "7ea12968-7758-40b6-8c73-75cc99be762b",
+      "7ea12968-7758-40b6-8c73-39bc3b6707a9",
+      "7ea12968-7758-40b6-8c73-97bb9901010d",
+    ],
+  }
+}
+```
diff --git a/sites/backend/openapi/apikeys.mjs b/sites/backend/openapi/apikeys.mjs
@@ -32,7 +32,7 @@ delete local.response.body.regular.properties.secret
 // Paths
 export const paths = {}
 
-// Create API key
+// List API keys or Create an API key
 paths['/apikeys/{auth}'] = {
   get: {
     ...common,
@@ -55,14 +55,7 @@ paths['/apikeys/{auth}'] = {
           },
         }),
       },
-      401: response.status['401'],
-      403: {
-        ...response.status['403'],
-        description:
-          response.status['403'].description +
-          errorExamples(['accountStatusLacking', 'insufficientAccessLevel']),
-      },
-      500: response.status['500'],
+      404: response.status['404'],
     },
   },
   post: {