@apifreaks/openapi-specs 0.1.0

package/specs/geodb/regions.json

@@ -0,0 +1,109 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Regions API - Retrieve World Regions & Subregions",
+    "version": "1.0.0",
+    "description": "Retrieve all geographical regions supported by the GeoDB service. Returns a flat array of exactly 6 region names - Africa, Americas, Asia, Europe, Oceania, and Polar. This endpoint takes no required parameters, ignores unrecognized query parameters rather than erroring, and has no documented error responses. Use the returned region names with the Subregions endpoint to drill down into subregional data.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Regions API Server"
+    }
+  ],
+  "paths": {
+    "/geo/regions": {
+      "get": {
+        "tags": ["GeoDB APIs"],
+        "summary": "Retrieve all geographical regions",
+        "description": "Returns all geographical regions supported by the service, such as Africa, Americas, Asia, Europe, Oceania, and Polar.",
+        "operationId": "getRegions",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response. Possible values: json, xml.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with list of regions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RegionsResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Typical successful response",
+                    "value": {
+                      "regions": [
+                        "Africa",
+                        "Americas",
+                        "Asia",
+                        "Europe",
+                        "Oceania",
+                        "Polar"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "RegionsResponse": {
+        "type": "object",
+        "description": "Response containing the flat list of geographical regions supported by the GeoDB service.",
+        "required": ["regions"],
+        "properties": {
+          "regions": {
+            "type": "array",
+            "description": "An array of region names representing all geographical regions supported by the service.",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/geodb/subregions.json

@@ -0,0 +1,217 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Subregions API Reference",
+    "version": "1.0.0",
+    "description": "Retrieve all subregions within a specified geographical region, or all subregions across every region when none is specified. The region parameter is optional. Returns a flat array of subregion names such as Western Europe, Southern Asia, or Northern America. Invalid region names return a 400 error; a region with no subregions (Polar) returns a 404.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Subregions API Server"
+    }
+  ],
+  "paths": {
+    "/geo/subregions": {
+      "get": {
+        "tags": ["GeoDB APIs"],
+        "summary": "Retrieve subregions for a specific geographical region",
+        "description": "Returns all subregions within a specified region, or all subregions across every region when the region parameter is omitted.",
+        "operationId": "getSubregionsByRegion",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Format of the response. Possible values: json, xml.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "region",
+            "in": "query",
+            "required": false,
+            "description": "Name of the region to retrieve subregions for. Omit to return all subregions across every region.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with list of subregions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SubregionsResponse"
+                },
+                "examples": {
+                  "typicalSuccess": {
+                    "summary": "Filtered by region=Europe",
+                    "value": {
+                      "subregions": [
+                        "Eastern Europe",
+                        "Northern Europe",
+                        "Southern Europe",
+                        "Western Europe"
+                      ]
+                    }
+                  },
+                  "allRegions": {
+                    "summary": "region parameter omitted — all 22 subregions across every region",
+                    "value": {
+                      "subregions": [
+                        "Australia and New Zealand",
+                        "Caribbean",
+                        "Central America",
+                        "Central Asia",
+                        "Eastern Africa",
+                        "Eastern Asia",
+                        "Eastern Europe",
+                        "Melanesia",
+                        "Micronesia",
+                        "Middle Africa",
+                        "Northern Africa",
+                        "Northern America",
+                        "Northern Europe",
+                        "Polynesia",
+                        "South America",
+                        "South-Eastern Asia",
+                        "Southern Africa",
+                        "Southern Asia",
+                        "Southern Europe",
+                        "Western Africa",
+                        "Western Asia",
+                        "Western Europe"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Region name is not a recognized region",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "InvalidRegionName": {
+                    "summary": "Invalid region name",
+                    "value": {
+                      "timestamp": "2026-07-24T11:00:12.748Z",
+                      "path": "/v1/subregions",
+                      "status": 400,
+                      "error": "Invalid Region Name provided",
+                      "message": "Please provide a valid region name."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found — Region is valid but has no subregions (e.g. Polar)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "NoSubregions": {
+                    "summary": "No subregions for this region",
+                    "value": {
+                      "timestamp": "2026-07-24T11:00:06.003Z",
+                      "path": "/v1/subregions",
+                      "status": 404,
+                      "error": "No subregions exist",
+                      "message": "This region does not have any subregions."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "SubregionsResponse": {
+        "type": "object",
+        "description": "Response containing subregion names for the requested region, or all subregions across every region when unfiltered.",
+        "required": ["subregions"],
+        "properties": {
+          "subregions": {
+            "type": "array",
+            "description": "An array of subregion names within the specified region.",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}