From 3e6d3da800388e917c627ce359f1720a9a30e7fd Mon Sep 17 00:00:00 2001 From: weaponsforge Date: Wed, 22 Apr 2026 18:56:23 +0800 Subject: [PATCH 1/4] feat: create a scalar api documentation, #22 - Loaded the scalar standalone api doc script from its cdn - Used scalar api doc as the default api documentation in the root url - Moved the redocly cli doc under /docs/redoc --- server/package.json | 2 +- server/public/docs/redoc/index.html | 623 ++++++++++++++++++++ server/public/index.html | 24 + server/public/openapi.json | 4 +- server/public/openapi.yaml | 4 +- server/src/scripts/openapi/docs/api.info.ts | 4 +- 6 files changed, 654 insertions(+), 7 deletions(-) create mode 100644 server/public/docs/redoc/index.html create mode 100644 server/public/index.html diff --git a/server/package.json b/server/package.json index 6228386..5e73a68 100644 --- a/server/package.json +++ b/server/package.json @@ -14,7 +14,7 @@ "transpile:noemit": "tsc -p tsconfig.json --noEmit", "docs:swagger": "tsx ./src/scripts/copyFiles/main.ts", "docs:gen": "tsx --import ./src/scripts/openapi/zod-extend.ts ./src/scripts/openapi/main.ts", - "docs:build": "npm run docs:gen && redocly build-docs ./public/openapi.yaml -o public/index.html", + "docs:build": "npm run docs:gen && redocly build-docs ./public/openapi.yaml -o public/docs/redoc/index.html", "build": "npm run transpile && npm run docs:build && npm run docs:swagger", "watch": "tsc -p tsconfig.json --watch", "lint": "eslint \"src/**/*.ts\" *.mjs", diff --git a/server/public/docs/redoc/index.html b/server/public/docs/redoc/index.html new file mode 100644 index 0000000..9aaf9c7 --- /dev/null +++ b/server/public/docs/redoc/index.html @@ -0,0 +1,623 @@ + + + + + + PH Regions API + + + + + + + + + +
PH Regions logo
API docs by Redocly

PH Regions API (1.0.0)

Download OpenAPI specification:

URL: https://github.com/weaponsforge/ph-regions License: MIT

💡About

+

A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes.

+

⚠️ Important

This API is intended for testing and simulating RESTful API requests from client applications. + Note: The location data may be outdated and does not reflect the most current official records.

+

🧩 Alternate API Documentation

+

Islands

REST APIs for retrieving Philippine islands location data

+

List islands

List of main island group names in the Philippines

+
query Parameters
name
string <= 40 characters
Example: name=Luzon

Island name

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

List full islands

Full list of main island groups in the Philippines including regions

+
query Parameters
name
string <= 40 characters
Example: name=Luzon

Island name

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

Get island by ID

Get an island data by ID

+
path Parameters
id
required
string
Example: 68bc452af0a9414a4312e589

Island document ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": {
    }
}

Regions

REST APIs for retrieving Philippine regional location data

+

List regions

List of regions in the Philippines (excluding provinces and municipalities)

+
query Parameters
islandId
string
Example: islandId=68bc452af0a9414a4312e589

Island document ID

+
name
string <= 40 characters
Example: name=Region IV-A

Region name

+
abbrev
string or null <= 20 characters
Example: abbrev=CALABARZON

Abbreviation name or code

+
regionalName
string
Example: regionalName=CALABARZON

Long-form regional name

+
regionalCode
string or null <= 5 characters
Example: regionalCode=4A

Region code

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

List full regions

Full list of regions data in the Philippines including provinces and municipalities

+
query Parameters
islandId
string
Example: islandId=68bc452af0a9414a4312e589

Island document ID

+
name
string <= 40 characters
Example: name=Region IV-A

Region name

+
abbrev
string or null <= 20 characters
Example: abbrev=CALABARZON

Abbreviation name or code

+
regionalName
string
Example: regionalName=CALABARZON

Long-form regional name

+
regionalCode
string or null <= 5 characters
Example: regionalCode=4A

Region code

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

Get region by ID

Retrieves region data by ID excluding provinces and municipalities

+
path Parameters
id
required
string
Example: 68bc452bf0a9414a4312e591

Region ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": {
    }
}

Get region by ID with provinces

Retrieves region data by ID including all provinces and municipalities

+
path Parameters
id
required
string
Example: 68bc452bf0a9414a4312e591

Region ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": {
    }
}

Provinces

REST APIs for retrieving Philippine provincial location data

+

List provinces

List of provinces in the Philippines (excluding municipalities)

+
query Parameters
regionId
string
Example: regionId=68bc452bf0a9414a4312e591

Region ID

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

List full provinces

Full list of provinces in the Philippines including municipalities

+
query Parameters
regionId
string
Example: regionId=68bc452bf0a9414a4312e591

Region ID

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

Get province by ID

Get province data by ID excluding municipalities

+
path Parameters
id
required
string
Example: 68bc452bf0a9414a4312e5b1

Province ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": {
    }
}

Get province by ID with municipalities

Get province data by ID including its municipalities

+
path Parameters
id
required
string
Example: 68bc452bf0a9414a4312e5b1

Province ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": {
    }
}

Municipalities

REST APIs for retrieving Philippine municipal location data

+

List municipalities

List of municipalities in the Philippines by region or province

+
query Parameters
regionId
string
Example: regionId=68bc452bf0a9414a4312e591

Region ID

+
provinceId
string
Example: provinceId=68bc452bf0a9414a4312e5b1

Province ID

+
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": [
    ]
}

Get municipality by ID

Retrieves municipality data by ID

+
path Parameters
id
required
string
Example: 68bc452bf0a9414a4312e753

Municipality ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "total": 1,
  • "metadata": {
    },
  • "data": {
    }
}

Stats

REST APIs for retrieving random test data for each Municipality

+

Get municipality stats by ID

Retrieves municipality stats data by ID

+
path Parameters
id
required
string
Example: 68bc452bf0a9414a4312e753

Municipality ID

+
query Parameters
includeMeta
boolean or null
Default: false
Example: includeMeta=false

Flag to include the Mongo meta fields (eg., createdAt, updatedAt) in the response

+

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "metadata": {
    },
  • "data": {
    }
}
+ + + + diff --git a/server/public/index.html b/server/public/index.html new file mode 100644 index 0000000..02c6158 --- /dev/null +++ b/server/public/index.html @@ -0,0 +1,24 @@ + + + + PH Regions API Docs (Scalar) + + + + +
+ + + + + + + + diff --git a/server/public/openapi.json b/server/public/openapi.json index 5a406b3..16a17c8 100644 --- a/server/public/openapi.json +++ b/server/public/openapi.json @@ -10,9 +10,9 @@ "license": { "name": "MIT" }, - "description": "**💡About** \n\n A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes. \n\n **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. \n **Note:** The location data may be outdated and does not reflect the most current official records. \n\n **🧩 Alternate Docs** ", + "description": "**💡About** \n\n A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes. \n\n **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. \n **Note:** The location data may be outdated and does not reflect the most current official records. \n\n **🧩 Alternate API Documentation** ", "x-logo": { - "url": "./assets/images/logo_ph_regions_01.png", + "url": "../../assets/images/logo_ph_regions_01.png", "altText": "PH Regions logo" } }, diff --git a/server/public/openapi.yaml b/server/public/openapi.yaml index 02bbe28..2475480 100644 --- a/server/public/openapi.yaml +++ b/server/public/openapi.yaml @@ -15,9 +15,9 @@ info: **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. **Note:** The location data may be outdated and does not reflect the most current official records. - **🧩 Alternate Docs** + **🧩 Alternate API Documentation** x-logo: - url: ./assets/images/logo_ph_regions_01.png + url: ../../assets/images/logo_ph_regions_01.png altText: PH Regions logo tags: - name: Islands diff --git a/server/src/scripts/openapi/docs/api.info.ts b/server/src/scripts/openapi/docs/api.info.ts index 061eaa6..bff9674 100644 --- a/server/src/scripts/openapi/docs/api.info.ts +++ b/server/src/scripts/openapi/docs/api.info.ts @@ -10,10 +10,10 @@ export const API_INFO = { contact: { name: 'PH Regions', url: 'https://github.com/weaponsforge/ph-regions' }, license: { name: 'MIT' }, - description: `**💡About** \n\n A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes. \n\n **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. \n **Note:** The location data may be outdated and does not reflect the most current official records. \n\n **🧩 Alternate Docs** `, + description: `**💡About** \n\n A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes. \n\n **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. \n **Note:** The location data may be outdated and does not reflect the most current official records. \n\n **🧩 Alternate API Documentation** `, 'x-logo': { - url: './assets/images/logo_ph_regions_01.png', + url: '../../assets/images/logo_ph_regions_01.png', altText: 'PH Regions logo', }, }, From 4fa350407f57ba8c2da7665241e5bf3dce24e358 Mon Sep 17 00:00:00 2001 From: weaponsforge Date: Wed, 22 Apr 2026 19:05:19 +0800 Subject: [PATCH 2/4] chore: update dependencies 20260422 - Update @redocly/cli 2.28.1 -> 2.29.1 - Update mongoose 9.4.1 -> 9.5.0 - Update typescript-eslint 8.58.2 -> 8.59.0 - Bump to version minor v1.2.0 --- server/package-lock.json | 230 ++++++++++++++++++--------------------- server/package.json | 8 +- 2 files changed, 112 insertions(+), 126 deletions(-) diff --git a/server/package-lock.json b/server/package-lock.json index 4582862..4eeab7d 100644 --- a/server/package-lock.json +++ b/server/package-lock.json @@ -1,12 +1,12 @@ { "name": "ph-regions", - "version": "1.1.3", + "version": "1.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ph-regions", - "version": "1.1.3", + "version": "1.2.0", "license": "MIT", "dependencies": { "cookie-parser": "^1.4.7", @@ -14,14 +14,14 @@ "dotenv": "^17.4.2", "express": "^5.2.1", "express-rate-limit": "^8.3.2", - "mongoose": "^9.4.1", + "mongoose": "^9.5.0", "swagger-ui-express": "^5.0.1", "zod": "^4.3.6" }, "devDependencies": { "@asteasolutions/zod-to-openapi": "^8.5.0", "@eslint/js": "^10.0.1", - "@redocly/cli": "^2.28.1", + "@redocly/cli": "^2.29.1", "@types/cookie-parser": "^1.4.10", "@types/cors": "^2.8.19", "@types/express": "^5.0.6", @@ -33,7 +33,7 @@ "tsc-alias": "^1.8.16", "tsx": "^4.21.0", "typescript": "^6.0.3", - "typescript-eslint": "^8.58.2", + "typescript-eslint": "^8.59.0", "yaml": "^2.8.3" }, "engines": { @@ -855,7 +855,6 @@ "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==", "dev": true, "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=8.0.0" } @@ -1158,9 +1157,9 @@ "license": "MIT" }, "node_modules/@redocly/cli": { - "version": "2.28.1", - "resolved": "https://registry.npmjs.org/@redocly/cli/-/cli-2.28.1.tgz", - "integrity": "sha512-gDi0+vC905YHrtGD3WCP86gW44JdXQb0fu4128tVFpgfh5T65tFZkhs2xoPqLJn7RCtkndQ+rSwyXcALKoao0A==", + "version": "2.29.1", + "resolved": "https://registry.npmjs.org/@redocly/cli/-/cli-2.29.1.tgz", + "integrity": "sha512-n85tU21emkYc1k7IZhOFqIrEQizvQuHzHMOwcMZ503XNhzf9OYLLQ8AEcQl1hjpUGtJWsMeSJbpuEwewgb4T0Q==", "dev": true, "license": "MIT", "dependencies": { @@ -1169,8 +1168,8 @@ "@opentelemetry/sdk-trace-node": "2.0.1", "@opentelemetry/semantic-conventions": "1.34.0", "@redocly/cli-otel": "0.1.2", - "@redocly/openapi-core": "2.28.1", - "@redocly/respect-core": "2.28.1", + "@redocly/openapi-core": "2.29.1", + "@redocly/respect-core": "2.29.1", "abort-controller": "^3.0.0", "ajv": "npm:@redocly/ajv@8.18.0", "ajv-formats": "^3.0.1", @@ -1285,9 +1284,9 @@ } }, "node_modules/@redocly/openapi-core": { - "version": "2.28.1", - "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-2.28.1.tgz", - "integrity": "sha512-PXulQY+lUJzeLWfhtJ8UPBFaMvlPDvW/dkozDhUAlYDotEYNMOaKFbJxKcrPCtRYtZ0TJsh5MohdcDLCBAJbFg==", + "version": "2.29.1", + "resolved": "https://registry.npmjs.org/@redocly/openapi-core/-/openapi-core-2.29.1.tgz", + "integrity": "sha512-T9FeS2+lpXR9V/XHqiJ53uGjoF1Hs80nRA9ACEXpTLF9a4jzzSANO92/f9HKuQvl0bHgyaIbP5OsBgVU3EP1KQ==", "dev": true, "license": "MIT", "dependencies": { @@ -1346,16 +1345,16 @@ } }, "node_modules/@redocly/respect-core": { - "version": "2.28.1", - "resolved": "https://registry.npmjs.org/@redocly/respect-core/-/respect-core-2.28.1.tgz", - "integrity": "sha512-r8sf7damvSviJwVif4hZVP/Qw7ciLgwLvHVy9AsUWxWh6JQtTZpV2/lJB681bqjn+GM9EMzhcNL1rBUo4K6Uyg==", + "version": "2.29.1", + "resolved": "https://registry.npmjs.org/@redocly/respect-core/-/respect-core-2.29.1.tgz", + "integrity": "sha512-TklpmSho4nSp2ySXWRUJlFQaHoN4BtSTTWabzQPetblAJ6KRVZtgFk6x8eD8KwWUaJj8c7ed4/KAIHOqTdNVxg==", "dev": true, "license": "MIT", "dependencies": { "@faker-js/faker": "^7.6.0", "@noble/hashes": "^1.8.0", "@redocly/ajv": "^8.18.0", - "@redocly/openapi-core": "2.28.1", + "@redocly/openapi-core": "2.29.1", "ajv": "npm:@redocly/ajv@8.18.0", "better-ajv-errors": "^1.2.0", "colorette": "^2.0.20", @@ -1483,7 +1482,6 @@ "integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@types/body-parser": "*", "@types/express-serve-static-core": "^5.0.0", @@ -1612,17 +1610,17 @@ } }, "node_modules/@typescript-eslint/eslint-plugin": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.58.2.tgz", - "integrity": "sha512-aC2qc5thQahutKjP+cl8cgN9DWe3ZUqVko30CMSZHnFEHyhOYoZSzkGtAI2mcwZ38xeImDucI4dnqsHiOYuuCw==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.59.0.tgz", + "integrity": "sha512-HyAZtpdkgZwpq8Sz3FSUvCR4c+ScbuWa9AksK2Jweub7w4M3yTz4O11AqVJzLYjy/B9ZWPyc81I+mOdJU/bDQw==", "dev": true, "license": "MIT", "dependencies": { "@eslint-community/regexpp": "^4.12.2", - "@typescript-eslint/scope-manager": "8.58.2", - "@typescript-eslint/type-utils": "8.58.2", - "@typescript-eslint/utils": "8.58.2", - "@typescript-eslint/visitor-keys": "8.58.2", + "@typescript-eslint/scope-manager": "8.59.0", + "@typescript-eslint/type-utils": "8.59.0", + "@typescript-eslint/utils": "8.59.0", + "@typescript-eslint/visitor-keys": "8.59.0", "ignore": "^7.0.5", "natural-compare": "^1.4.0", "ts-api-utils": "^2.5.0" @@ -1635,7 +1633,7 @@ "url": "https://opencollective.com/typescript-eslint" }, "peerDependencies": { - "@typescript-eslint/parser": "^8.58.2", + "@typescript-eslint/parser": "^8.59.0", "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } @@ -1651,17 +1649,16 @@ } }, "node_modules/@typescript-eslint/parser": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.58.2.tgz", - "integrity": "sha512-/Zb/xaIDfxeJnvishjGdcR4jmr7S+bda8PKNhRGdljDM+elXhlvN0FyPSsMnLmJUrVG9aPO6dof80wjMawsASg==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.59.0.tgz", + "integrity": "sha512-TI1XGwKbDpo9tRW8UDIXCOeLk55qe9ZFGs8MTKU6/M08HWTw52DD/IYhfQtOEhEdPhLMT26Ka/x7p70nd3dzDg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { - "@typescript-eslint/scope-manager": "8.58.2", - "@typescript-eslint/types": "8.58.2", - "@typescript-eslint/typescript-estree": "8.58.2", - "@typescript-eslint/visitor-keys": "8.58.2", + "@typescript-eslint/scope-manager": "8.59.0", + "@typescript-eslint/types": "8.59.0", + "@typescript-eslint/typescript-estree": "8.59.0", + "@typescript-eslint/visitor-keys": "8.59.0", "debug": "^4.4.3" }, "engines": { @@ -1677,14 +1674,14 @@ } }, "node_modules/@typescript-eslint/project-service": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.58.2.tgz", - "integrity": "sha512-Cq6UfpZZk15+r87BkIh5rDpi38W4b+Sjnb8wQCPPDDweS/LRCFjCyViEbzHk5Ck3f2QDfgmlxqSa7S7clDtlfg==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.59.0.tgz", + "integrity": "sha512-Lw5ITrR5s5TbC19YSvlr63ZfLaJoU6vtKTHyB0GQOpX0W7d5/Ir6vUahWi/8Sps/nOukZQ0IB3SmlxZnjaKVnw==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/tsconfig-utils": "^8.58.2", - "@typescript-eslint/types": "^8.58.2", + "@typescript-eslint/tsconfig-utils": "^8.59.0", + "@typescript-eslint/types": "^8.59.0", "debug": "^4.4.3" }, "engines": { @@ -1699,14 +1696,14 @@ } }, "node_modules/@typescript-eslint/scope-manager": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.58.2.tgz", - "integrity": "sha512-SgmyvDPexWETQek+qzZnrG6844IaO02UVyOLhI4wpo82dpZJY9+6YZCKAMFzXb7qhx37mFK1QcPQ18tud+vo6Q==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.59.0.tgz", + "integrity": "sha512-UzR16Ut8IpA3Mc4DbgAShlPPkVm8xXMWafXxB0BocaVRHs8ZGakAxGRskF7FId3sdk9lgGD73GSFaWmWFDE4dg==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/types": "8.58.2", - "@typescript-eslint/visitor-keys": "8.58.2" + "@typescript-eslint/types": "8.59.0", + "@typescript-eslint/visitor-keys": "8.59.0" }, "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -1717,9 +1714,9 @@ } }, "node_modules/@typescript-eslint/tsconfig-utils": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.58.2.tgz", - "integrity": "sha512-3SR+RukipDvkkKp/d0jP0dyzuls3DbGmwDpVEc5wqk5f38KFThakqAAO0XMirWAE+kT00oTauTbzMFGPoAzB0A==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.59.0.tgz", + "integrity": "sha512-91Sbl3s4Kb3SybliIY6muFBmHVv+pYXfybC4Oolp3dvk8BvIE3wOPc+403CWIT7mJNkfQRGtdqghzs2+Z91Tqg==", "dev": true, "license": "MIT", "engines": { @@ -1734,15 +1731,15 @@ } }, "node_modules/@typescript-eslint/type-utils": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.58.2.tgz", - "integrity": "sha512-Z7EloNR/B389FvabdGeTo2XMs4W9TjtPiO9DAsmT0yom0bwlPyRjkJ1uCdW1DvrrrYP50AJZ9Xc3sByZA9+dcg==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/type-utils/-/type-utils-8.59.0.tgz", + "integrity": "sha512-3TRiZaQSltGqGeNrJzzr1+8YcEobKH9rHnqIp/1psfKFmhRQDNMGP5hBufanYTGznwShzVLs3Mz+gDN7HkWfXg==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/types": "8.58.2", - "@typescript-eslint/typescript-estree": "8.58.2", - "@typescript-eslint/utils": "8.58.2", + "@typescript-eslint/types": "8.59.0", + "@typescript-eslint/typescript-estree": "8.59.0", + "@typescript-eslint/utils": "8.59.0", "debug": "^4.4.3", "ts-api-utils": "^2.5.0" }, @@ -1759,9 +1756,9 @@ } }, "node_modules/@typescript-eslint/types": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.58.2.tgz", - "integrity": "sha512-9TukXyATBQf/Jq9AMQXfvurk+G5R2MwfqQGDR2GzGz28HvY/lXNKGhkY+6IOubwcquikWk5cjlgPvD2uAA7htQ==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.59.0.tgz", + "integrity": "sha512-nLzdsT1gdOgFxxxwrlNVUBzSNBEEHJ86bblmk4QAS6stfig7rcJzWKqCyxFy3YRRHXDWEkb2NralA1nOYkkm/A==", "dev": true, "license": "MIT", "engines": { @@ -1773,16 +1770,16 @@ } }, "node_modules/@typescript-eslint/typescript-estree": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.58.2.tgz", - "integrity": "sha512-ELGuoofuhhoCvNbQjFFiobFcGgcDCEm0ThWdmO4Z0UzLqPXS3KFvnEZ+SHewwOYHjM09tkzOWXNTv9u6Gqtyuw==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.59.0.tgz", + "integrity": "sha512-O9Re9P1BmBLFJyikRbQpLku/QA3/AueZNO9WePLBwQrvkixTmDe8u76B6CYUAITRl/rHawggEqUGn5QIkVRLMw==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/project-service": "8.58.2", - "@typescript-eslint/tsconfig-utils": "8.58.2", - "@typescript-eslint/types": "8.58.2", - "@typescript-eslint/visitor-keys": "8.58.2", + "@typescript-eslint/project-service": "8.59.0", + "@typescript-eslint/tsconfig-utils": "8.59.0", + "@typescript-eslint/types": "8.59.0", + "@typescript-eslint/visitor-keys": "8.59.0", "debug": "^4.4.3", "minimatch": "^10.2.2", "semver": "^7.7.3", @@ -1801,16 +1798,16 @@ } }, "node_modules/@typescript-eslint/utils": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.58.2.tgz", - "integrity": "sha512-QZfjHNEzPY8+l0+fIXMvuQ2sJlplB4zgDZvA+NmvZsZv3EQwOcc1DuIU1VJUTWZ/RKouBMhDyNaBMx4sWvrzRA==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/utils/-/utils-8.59.0.tgz", + "integrity": "sha512-I1R/K7V07XsMJ12Oaxg/O9GfrysGTmCRhvZJBv0RE0NcULMzjqVpR5kRRQjHsz3J/bElU7HwCO7zkqL+MSUz+g==", "dev": true, "license": "MIT", "dependencies": { "@eslint-community/eslint-utils": "^4.9.1", - "@typescript-eslint/scope-manager": "8.58.2", - "@typescript-eslint/types": "8.58.2", - "@typescript-eslint/typescript-estree": "8.58.2" + "@typescript-eslint/scope-manager": "8.59.0", + "@typescript-eslint/types": "8.59.0", + "@typescript-eslint/typescript-estree": "8.59.0" }, "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -1825,13 +1822,13 @@ } }, "node_modules/@typescript-eslint/visitor-keys": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.58.2.tgz", - "integrity": "sha512-f1WO2Lx8a9t8DARmcWAUPJbu0G20bJlj8L4z72K00TMeJAoyLr/tHhI/pzYBLrR4dXWkcxO1cWYZEOX8DKHTqA==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.59.0.tgz", + "integrity": "sha512-/uejZt4dSere1bx12WLlPfv8GktzcaDtuJ7s42/HEZ5zGj9oxRaD4bj7qwSunXkf+pbAhFt2zjpHYUiT5lHf0Q==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/types": "8.58.2", + "@typescript-eslint/types": "8.59.0", "eslint-visitor-keys": "^5.0.0" }, "engines": { @@ -1874,7 +1871,6 @@ "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==", "dev": true, "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -1908,7 +1904,6 @@ "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -2193,29 +2188,6 @@ "url": "https://github.com/chalk/chalk?sponsor=1" } }, - "node_modules/chalk/node_modules/has-flag": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", - "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" - } - }, - "node_modules/chalk/node_modules/supports-color": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", - "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", - "dev": true, - "license": "MIT", - "dependencies": { - "has-flag": "^4.0.0" - }, - "engines": { - "node": ">=8" - } - }, "node_modules/chokidar": { "version": "3.6.0", "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz", @@ -2654,7 +2626,6 @@ "integrity": "sha512-wiyGaKsDgqXvF40P8mDwiUp/KQjE1FdrIEJsM8PZ3XCiniTMXS3OHWWUe5FI5agoCnr8x4xPrTDZuxsBlNHl+Q==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.2", @@ -2845,7 +2816,6 @@ "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz", "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", "license": "MIT", - "peer": true, "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", @@ -3310,6 +3280,16 @@ "uglify-js": "^3.1.4" } }, + "node_modules/has-flag": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", + "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, "node_modules/has-symbols": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", @@ -3601,9 +3581,9 @@ } }, "node_modules/kareem": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/kareem/-/kareem-3.2.0.tgz", - "integrity": "sha512-VS8MWZz/cT+SqBCpVfNN4zoVz5VskR3N4+sTmUXme55e9avQHntpwpNq0yjnosISXqwJ3AQVjlbI4Dyzv//JtA==", + "version": "3.3.0", + "resolved": "https://registry.npmjs.org/kareem/-/kareem-3.3.0.tgz", + "integrity": "sha512-kpSuLD3/7RenBnjnJdOHXCKC8dTd1JzeOiJhN0necWWci6cC+qX+VuwPnMVgb+a4+KNJSfgqahpnfWaeDXCimw==", "license": "Apache-2.0", "engines": { "node": ">=18.0.0" @@ -3839,7 +3819,6 @@ "integrity": "sha512-UczzB+0nnwGotYSgllfARAqWCJ5e/skuV2K/l+Zyck/H6pJIhLXuBnz+6vn2i211o7DtbE78HQtsYEKICHGI+g==", "dev": true, "license": "MIT", - "peer": true, "funding": { "type": "opencollective", "url": "https://opencollective.com/mobx" @@ -3957,12 +3936,12 @@ } }, "node_modules/mongoose": { - "version": "9.4.1", - "resolved": "https://registry.npmjs.org/mongoose/-/mongoose-9.4.1.tgz", - "integrity": "sha512-4rFBWa+/wdBQSfvnOPJBpiSG6UCEbhSQh865dEdaH9Y8WfHBUC+I2XT28dp0IBIGrEwmh+gzrgZgea5PbmrHWA==", + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/mongoose/-/mongoose-9.5.0.tgz", + "integrity": "sha512-B4blGFkFL1s0G24URuMvx0qTlx+gRVLmfO7WcSz8NcmW/XHEJ3G69capdyW1iRsGKiycp1tkwKHnxHbnwjwmPw==", "license": "MIT", "dependencies": { - "kareem": "3.2.0", + "kareem": "3.3.0", "mongodb": "~7.1", "mpath": "0.9.0", "mquery": "6.0.0", @@ -4740,7 +4719,6 @@ "integrity": "sha512-llUJLzz1zTUBrskt2pwZgLq59AemifIftw4aB7JxOqf1HY2FDaGDxgwpAPVzHU1kdWabH7FauP4i1oEeer2WCA==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -4751,7 +4729,6 @@ "integrity": "sha512-J5bAZz+DXMMwW/wV3xzKke59Af6CHY7G4uYLN1OvBcKEsWOs4pQExj86BBKamxl/Ik5bx9whOrvBlSDfWzgSag==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -5436,7 +5413,6 @@ "integrity": "sha512-J72R4ltw0UBVUlEjTzI0gg2STOqlI9JBhQOL4Dxt7aJOnnSesy0qJDn4PYfMCafk9cWOaVg129Pesl5o+DIh0Q==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@emotion/is-prop-valid": "1.4.0", "@emotion/unitless": "0.10.0", @@ -5472,6 +5448,19 @@ "dev": true, "license": "MIT" }, + "node_modules/supports-color": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", + "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-flag": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, "node_modules/swagger-ui-dist": { "version": "5.29.0", "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-5.29.0.tgz", @@ -5575,7 +5564,6 @@ "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=12" }, @@ -5719,7 +5707,6 @@ "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", "dev": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -5729,16 +5716,16 @@ } }, "node_modules/typescript-eslint": { - "version": "8.58.2", - "resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.58.2.tgz", - "integrity": "sha512-V8iSng9mRbdZjl54VJ9NKr6ZB+dW0J3TzRXRGcSbLIej9jV86ZRtlYeTKDR/QLxXykocJ5icNzbsl2+5TzIvcQ==", + "version": "8.59.0", + "resolved": "https://registry.npmjs.org/typescript-eslint/-/typescript-eslint-8.59.0.tgz", + "integrity": "sha512-BU3ONW9X+v90EcCH9ZS6LMackcVtxRLlI3XrYyqZIwVSHIk7Qf7bFw1z0M9Q0IUxhTMZCf8piY9hTYaNEIASrw==", "dev": true, "license": "MIT", "dependencies": { - "@typescript-eslint/eslint-plugin": "8.58.2", - "@typescript-eslint/parser": "8.58.2", - "@typescript-eslint/typescript-estree": "8.58.2", - "@typescript-eslint/utils": "8.58.2" + "@typescript-eslint/eslint-plugin": "8.59.0", + "@typescript-eslint/parser": "8.59.0", + "@typescript-eslint/typescript-estree": "8.59.0", + "@typescript-eslint/utils": "8.59.0" }, "engines": { "node": "^18.18.0 || ^20.9.0 || >=21.1.0" @@ -6046,7 +6033,6 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz", "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/server/package.json b/server/package.json index 5e73a68..f0be767 100644 --- a/server/package.json +++ b/server/package.json @@ -1,6 +1,6 @@ { "name": "ph-regions", - "version": "1.1.3", + "version": "1.2.0", "type": "module", "description": "A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality.", "main": "dist/server.js", @@ -33,14 +33,14 @@ "dotenv": "^17.4.2", "express": "^5.2.1", "express-rate-limit": "^8.3.2", - "mongoose": "^9.4.1", + "mongoose": "^9.5.0", "swagger-ui-express": "^5.0.1", "zod": "^4.3.6" }, "devDependencies": { "@asteasolutions/zod-to-openapi": "^8.5.0", "@eslint/js": "^10.0.1", - "@redocly/cli": "^2.28.1", + "@redocly/cli": "^2.29.1", "@types/cookie-parser": "^1.4.10", "@types/cors": "^2.8.19", "@types/express": "^5.0.6", @@ -52,7 +52,7 @@ "tsc-alias": "^1.8.16", "tsx": "^4.21.0", "typescript": "^6.0.3", - "typescript-eslint": "^8.58.2", + "typescript-eslint": "^8.59.0", "yaml": "^2.8.3" } } From a3ded690c24a52a2edd40fbd0ab10541879dec10 Mon Sep 17 00:00:00 2001 From: weaponsforge Date: Wed, 22 Apr 2026 19:10:16 +0800 Subject: [PATCH 3/4] docs: update README --- README.md | 6 ++++-- server/src/scripts/openapi/docs/api.info.ts | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 620e9e6..5dd4be5 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,10 @@ A RESTful API that serves **hierarchical location data** of the Philippines — - REST API: - API documentation - - Static: - - Interactive: + - Interactive (Scalar): + - Interactive (Swagger UI): + - Static: +
diff --git a/server/src/scripts/openapi/docs/api.info.ts b/server/src/scripts/openapi/docs/api.info.ts index bff9674..26f3726 100644 --- a/server/src/scripts/openapi/docs/api.info.ts +++ b/server/src/scripts/openapi/docs/api.info.ts @@ -10,7 +10,7 @@ export const API_INFO = { contact: { name: 'PH Regions', url: 'https://github.com/weaponsforge/ph-regions' }, license: { name: 'MIT' }, - description: `**💡About** \n\n A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes. \n\n **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. \n **Note:** The location data may be outdated and does not reflect the most current official records. \n\n **🧩 Alternate API Documentation**
  • Scalar: [${BASE_API_URL}](${BASE_API_URL})
  • Swagger UI: [${BASE_API_URL}/docs](${BASE_API_URL}/docs)
  • Redocly CLI: [${BASE_API_URL}/docs/redoc](${BASE_API_URL}/docs/redoc)
`, + description: `**💡About** \n\n A RESTful API that serves hierarchical location data of the Philippines — including regions, provinces, municipalities, and a randomly generated number of barangays per municipality for testing purposes. \n\n **⚠️ Important**

This API is intended for testing and simulating RESTful API requests from client applications. \n **Note:** The location data may be outdated and does not reflect the most current official records. \n\n **🧩 Alternate API Documentation**
  • Interactive (Scalar): [${BASE_API_URL}](${BASE_API_URL})
  • Interactive (Swagger UI): [${BASE_API_URL}/docs](${BASE_API_URL}/docs)
  • Static (Redocly CLI): [${BASE_API_URL}/docs/redoc](${BASE_API_URL}/docs/redoc)
`, 'x-logo': { url: '../../assets/images/logo_ph_regions_01.png', From cf3ebd24365da25ae6908e3ff5f5e2b3e16df1e9 Mon Sep 17 00:00:00 2001 From: weaponsforge Date: Wed, 22 Apr 2026 19:44:59 +0800 Subject: [PATCH 4/4] chore: apply pr review suggestions --- server/public/index.html | 6 +++++- server/src/scripts/openapi/docs/api.info.ts | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/server/public/index.html b/server/public/index.html index 02c6158..710969b 100644 --- a/server/public/index.html +++ b/server/public/index.html @@ -9,7 +9,11 @@
- +