feat: improve openapi docs

openstream-fm · Jan 14, 2024 · d9c90ee · d9c90ee
1 parent e5aee64
commit d9c90ee
Show file tree

Hide file tree

Showing 17 changed files with 1,314 additions and 33 deletions.
diff --git a/defs/api/accounts/GET/Query.schema.json b/defs/api/accounts/GET/Query.schema.json
@@ -12,7 +12,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/admins/GET/Query.schema.json b/defs/api/admins/GET/Query.schema.json
@@ -8,7 +8,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/invitations/GET/Query.schema.json b/defs/api/invitations/GET/Query.schema.json
@@ -24,7 +24,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/me/api-keys/GET/Query.schema.json b/defs/api/me/api-keys/GET/Query.schema.json
@@ -16,7 +16,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/me/devices/GET/Query.schema.json b/defs/api/me/devices/GET/Query.schema.json
@@ -16,7 +16,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/payment-methods/GET/Query.schema.json b/defs/api/payment-methods/GET/Query.schema.json
@@ -12,7 +12,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/plans/GET/Query.schema.json b/defs/api/plans/GET/Query.schema.json
@@ -9,7 +9,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/stations/GET/Query.schema.json b/defs/api/stations/GET/Query.schema.json
@@ -12,7 +12,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/api/stations/[station]/files/GET/Query.schema.json b/defs/api/stations/[station]/files/GET/Query.schema.json
@@ -8,7 +8,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     }

diff --git a/defs/api/stream-connections/GET/Query.schema.json b/defs/api/stream-connections/GET/Query.schema.json
@@ -32,7 +32,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     }

diff --git a/defs/api/users/GET/Query.schema.json b/defs/api/users/GET/Query.schema.json
@@ -8,7 +8,7 @@
       "minimum": 0.0
     },
     "limit": {
-      "default": 60,
+      "default": 0,
       "type": "integer",
       "format": "int64"
     },

diff --git a/defs/error/PublicErrorPayload.schema.json b/defs/error/PublicErrorPayload.schema.json
@@ -0,0 +1,85 @@
+{
+  "type": "object",
+  "required": [
+    "error"
+  ],
+  "properties": {
+    "error": {
+      "type": "object",
+      "required": [
+        "code",
+        "message",
+        "status"
+      ],
+      "properties": {
+        "status": {
+          "type": "integer",
+          "format": "uint16",
+          "minimum": 0.0
+        },
+        "message": {
+          "type": "string"
+        },
+        "code": {
+          "type": "string",
+          "enum": [
+            "INTERNAL",
+            "RESOURCE_NOT_FOUND",
+            "TOO_MANY_REQUESTS",
+            "BAD_REQUEST",
+            "INTERNAL_DB",
+            "INTERNAL_SERIALIZE",
+            "IO_REQUEST",
+            "TOKEN_MISSING",
+            "TOKEN_MALFORMED",
+            "TOKEN_NOT_FOUND",
+            "TOKEN_USER_NOT_FOUND",
+            "TOKEN_STATION_NOT_FOUND",
+            "TOKEN_ADMIN_NOT_FOUND",
+            "TOKEN_OUT_OF_SCOPE",
+            "TOKEN_USER_ACCOUNT_NOT_OWNER",
+            "STATION_NOT_FOUND",
+            "ADMIN_NOT_FOUND",
+            "USER_NOT_FOUND",
+            "ACCOUNT_NOT_FOUND",
+            "AUDIO_FILE_NOT_FOUND",
+            "DEVICE_NOT_FOUND",
+            "API_KEY_NOT_FOUND",
+            "PLAN_NOT_FOUND",
+            "PAYMENT_METHOD_NOT_FOUND",
+            "INVITATION_NOT_FOUND",
+            "QUERY_STRING_INVALID",
+            "PAYLOAD_IO",
+            "PAYLOAD_JSON",
+            "PAYLOAD_TOO_LARGE",
+            "PAYLOAD_INVALID",
+            "USER_AUTH_FAILED",
+            "ADMIN_AUTH_FAILED",
+            "USER_EMAIL_EXISTS",
+            "ADMIN_EMAIL_EXISTS",
+            "UPLOAD_EMPTY",
+            "UPLOAD_QUOTA_EXCEEDED",
+            "UPLOAD_INTERNAL_SPAWN",
+            "UPLOAD_INTENRAL_IO",
+            "UPLOAD_EXIT",
+            "RANGE_INVALID",
+            "RANGE_NO_OVERLAP",
+            "PATCH_EMPTY",
+            "PATCH_INVALID",
+            "PATCH_OUT_OF_SCOPE",
+            "CONTENT_LENGTH_REQUIRED",
+            "UNRESOLVABLE_ADMIN_ME",
+            "UNRESOLVABLE_USER_ME",
+            "PLAYLIST_START_IS_LIVE",
+            "PLAYLIST_START_IS_EXTERNAL_RELAY",
+            "PLAYLIST_START_NO_FILES",
+            "RENDER_MAIL",
+            "SEND_MAIL",
+            "CREATE_STATION_ACCOUNT_LIMIT",
+            "PAYMENTS_PERFORM"
+          ]
+        }
+      }
+    }
+  }
+}
diff --git a/openapi-generator.js b/openapi-generator.js
@@ -30,6 +30,8 @@ const security = [
 
 const paths = {};
 
+const public_error_payload = JSON.parse(fs.readFileSync(`${__dirname}/defs/error/PublicErrorPayload.schema.json`));
+
 const process_dir = (target) => {
   const full_target = `${basedir}${target == null ? "" : `/${target}`}`;
   const filenames = fs.readdirSync(full_target).sort();
@@ -97,12 +99,22 @@ const process_dir = (target) => {
 
         responses: {
           200: {
+            description: "A successful response",
             content: {
               "application/json": {
                 schema: output,
               },
             },
           },
+
+          default: {
+            description: "An error response with status, code and message fields",
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/Error" },
+              }
+            }
+          }
         },
       };
     }
@@ -150,12 +162,12 @@ const document = {
   info: {
     title: "Openstream Media Server API",
 
-    termsOfService: "https://openstream.fm/api-terms/",
+    // termsOfService: "https://openstream.fm/api-terms/",
 
-    license: {
-      name: "Apache 2.0",
-      url: "https://www.apache.org/licenses/LICENSE-2.0.html"
-    },
+    // license: {
+    //   name: "Apache 2.0",
+    //   url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+    // },
 
     version: "0.1.0",
   },
@@ -170,7 +182,11 @@ const document = {
   paths,
 
   components: {
-    securitySchemes,  
+    securitySchemes,
+
+    schemas: {
+      Error: public_error_payload,
+    }
   }
 }