Skip to content

Commit 9c72840

Browse files
weaponsforgeweaponsforge
authored
Merge pull request #31 from weaponsforge/feat/PHR-22
feat: scalar api documentation
2 parents 8023b23 + cf3ebd2 commit 9c72840

8 files changed

Lines changed: 774 additions & 135 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,10 @@ A RESTful API that serves **hierarchical location data** of the Philippines —
1313

1414
- REST API: <https://ph-regions.vercel.app/api>
1515
- API documentation
16-
- Static: <https://ph-regions.vercel.app>
17-
- Interactive: <https://ph-regions.vercel.app/docs>
16+
- Interactive (Scalar): <https://ph-regions.vercel.app>
17+
- Interactive (Swagger UI): <https://ph-regions.vercel.app/docs>
18+
- Static: <https://ph-regions.vercel.app/docs/redoc>
19+
1820

1921
<br>
2022

‎server/package-lock.json‎

Lines changed: 108 additions & 122 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎server/package.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "ph-regions",
3-
"version": "1.1.3",
3+
"version": "1.2.0",
44
"type": "module",
55
"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.",
66
"main": "dist/server.js",
@@ -14,7 +14,7 @@
1414
"transpile:noemit": "tsc -p tsconfig.json --noEmit",
1515
"docs:swagger": "tsx ./src/scripts/copyFiles/main.ts",
1616
"docs:gen": "tsx --import ./src/scripts/openapi/zod-extend.ts ./src/scripts/openapi/main.ts",
17-
"docs:build": "npm run docs:gen && redocly build-docs ./public/openapi.yaml -o public/index.html",
17+
"docs:build": "npm run docs:gen && redocly build-docs ./public/openapi.yaml -o public/docs/redoc/index.html",
1818
"build": "npm run transpile && npm run docs:build && npm run docs:swagger",
1919
"watch": "tsc -p tsconfig.json --watch",
2020
"lint": "eslint \"src/**/*.ts\" *.mjs",
@@ -33,14 +33,14 @@
3333
"dotenv": "^17.4.2",
3434
"express": "^5.2.1",
3535
"express-rate-limit": "^8.3.2",
36-
"mongoose": "^9.4.1",
36+
"mongoose": "^9.5.0",
3737
"swagger-ui-express": "^5.0.1",
3838
"zod": "^4.3.6"
3939
},
4040
"devDependencies": {
4141
"@asteasolutions/zod-to-openapi": "^8.5.0",
4242
"@eslint/js": "^10.0.1",
43-
"@redocly/cli": "^2.28.1",
43+
"@redocly/cli": "^2.29.1",
4444
"@types/cookie-parser": "^1.4.10",
4545
"@types/cors": "^2.8.19",
4646
"@types/express": "^5.0.6",
@@ -52,7 +52,7 @@
5252
"tsc-alias": "^1.8.16",
5353
"tsx": "^4.21.0",
5454
"typescript": "^6.0.3",
55-
"typescript-eslint": "^8.58.2",
55+
"typescript-eslint": "^8.59.0",
5656
"yaml": "^2.8.3"
5757
}
5858
}

‎server/public/docs/redoc/index.html‎

Lines changed: 623 additions & 0 deletions
Large diffs are not rendered by default.

‎server/public/index.html‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>PH Regions API Docs (Scalar)</title>
5+
<meta charset="utf-8" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1" />
7+
</head>
8+
<body>
9+
<div id="app"></div>
10+
11+
<!-- Load the Script -->
12+
<script
13+
src="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.52.5"
14+
integrity="sha384-CgK3WZXj+WGIkrmOoRUQVH/vp8sAA8d4DgYGSTK9DybAd4B7j9Ami1CbKXf+Q+pe"
15+
crossorigin="anonymous"
16+
></script>
17+
18+
<!-- Initialize the Scalar API Reference -->
19+
<script>
20+
Scalar.createApiReference('#app', {
21+
// The URL of the OpenAPI/Swagger document
22+
url: '/openapi.json',
23+
// Avoid CORS issues
24+
proxyUrl: 'https://proxy.scalar.com',
25+
})
26+
</script>
27+
</body>
28+
</html>

‎server/public/openapi.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@
1010
"license": {
1111
"name": "MIT"
1212
},
13-
"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** <br><br> 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** <ul><li>Interactive API documentation (Swagger UI): [http://localhost:3001/docs](http://localhost:3001/docs)</li></ul>",
13+
"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** <br><br> 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** <ul><li>Scalar: [http://localhost:3001](http://localhost:3001)</li><li>Swagger UI: [http://localhost:3001/docs](http://localhost:3001/docs)</li><li>Redocly CLI: [http://localhost:3001/docs/redoc](http://localhost:3001/docs/redoc)</li></ul>",
1414
"x-logo": {
15-
"url": "./assets/images/logo_ph_regions_01.png",
15+
"url": "../../assets/images/logo_ph_regions_01.png",
1616
"altText": "PH Regions logo"
1717
}
1818
},

‎server/public/openapi.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,9 @@ info:
1515
**⚠️ Important** <br><br> This API is intended for testing and simulating RESTful API requests from client applications.
1616
**Note:** The location data may be outdated and does not reflect the most current official records.
1717
18-
**🧩 Alternate Docs** <ul><li>Interactive API documentation (Swagger UI): [http://localhost:3001/docs](http://localhost:3001/docs)</li></ul>
18+
**🧩 Alternate API Documentation** <ul><li>Scalar: [http://localhost:3001](http://localhost:3001)</li><li>Swagger UI: [http://localhost:3001/docs](http://localhost:3001/docs)</li><li>Redocly CLI: [http://localhost:3001/docs/redoc](http://localhost:3001/docs/redoc)</li></ul>
1919
x-logo:
20-
url: ./assets/images/logo_ph_regions_01.png
20+
url: ../../assets/images/logo_ph_regions_01.png
2121
altText: PH Regions logo
2222
tags:
2323
- name: Islands

‎server/src/scripts/openapi/docs/api.info.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@ export const API_INFO = {
1010
contact: { name: 'PH Regions', url: 'https://github.com/weaponsforge/ph-regions' },
1111
license: { name: 'MIT' },
1212

13-
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** <br><br> 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** <ul><li>Interactive API documentation (Swagger UI): [${BASE_API_URL}/docs](${BASE_API_URL}/docs)</li></ul>`,
13+
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** <br><br> 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**\n\n- Interactive (Scalar): [${BASE_API_URL}](${BASE_API_URL})\n- Interactive (Swagger UI): [${BASE_API_URL}/docs](${BASE_API_URL}/docs)\n- Static (Redocly CLI): [${BASE_API_URL}/docs/redoc](${BASE_API_URL}/docs/redoc)`,
1414

1515
'x-logo': {
16-
url: './assets/images/logo_ph_regions_01.png',
16+
url: '../../assets/images/logo_ph_regions_01.png',
1717
altText: 'PH Regions logo',
1818
},
1919
},

0 commit comments

Comments
 (0)