Skip to content

Commit 318edd7

Browse files
devksingh4devksingh4
authored
Documentation Updates (#213)
1 parent 036f7e2 commit 318edd7

File tree

16 files changed

+420
-173
lines changed

16 files changed

+420
-173
lines changed

‎src/api/components/index.ts

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { AppRoles } from "common/roles.js";
1+
import { AppRoleHumanMapper, AppRoles } from "common/roles.js";
22
import { FastifyZodOpenApiSchema } from "fastify-zod-openapi";
33
import * as z from "zod/v4";
44
import { CoreOrganizationList } from "@acm-uiuc/js-shared";
@@ -208,10 +208,30 @@ export function withRoles<T extends FastifyZodOpenApiSchema>(
208208
security,
209209
"x-required-roles": roles,
210210
"x-disable-api-key-auth": disableApiKeyAuth,
211-
description:
212-
roles.length > 0
213-
? `${disableApiKeyAuth ? "API key authentication is not permitted for this route.\n\n" : ""}Requires one of the following roles: ${roles.join(", ")}.${schema.description ? `\n\n${schema.description}` : ""}`
214-
: "Requires valid authentication but no specific role.",
211+
description: `
212+
${
213+
disableApiKeyAuth
214+
? `
215+
> [!important]
216+
> This resource cannot be accessed with an API key.
217+
`
218+
: ""
219+
}
220+
221+
${
222+
schema.description
223+
? `
224+
#### Description
225+
<hr />
226+
${schema.description}
227+
`
228+
: ""
229+
}
230+
231+
#### Authorization
232+
<hr />
233+
${roles.length > 0 ? `Requires any of the following roles:\n\n${roles.map((item) => `* ${AppRoleHumanMapper[item]} (<code>${item}</code>)`).join("\n")}` : "Requires valid authentication but no specific authorization."}
234+
`,
215235
...schema,
216236
response: responses,
217237
};

‎src/api/createSwagger.ts

Lines changed: 2 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -2,145 +2,7 @@ import { fileURLToPath } from "url";
22
import path from "node:path";
33
import { writeFile, mkdir } from "fs/promises";
44
import init from "./index.js"; // Assuming this is your Fastify app initializer
5-
6-
const html = `
7-
<!doctype html>
8-
<html>
9-
<head>
10-
<title>Core API Documentation | ACM @ UIUC</title>
11-
<meta charset="utf-8" />
12-
<meta
13-
name="viewport"
14-
content="width=device-width, initial-scale=1" />
15-
<meta property="og:title" content="Core API Documentation | ACM @ UIUC" />
16-
<meta property="og:description" content="The ACM @ UIUC Core API provides services for managing chapter operations." />
17-
<meta property="description" content="The ACM @ UIUC Core API provides services for managing chapter operations." />
18-
<meta property="og:image" content="https://static.acm.illinois.edu/square-blue.png" />
19-
<meta property="og:url" content="https://core.acm.illinois.edu/docs" />
20-
<style>
21-
:root {
22-
--scalar-custom-header-height: 50px;
23-
/* Default colors (Light Mode) */
24-
--initial-bg-color: #FFFFFF; /* White */
25-
--initial-text-color: #2A2F45; /* Black */
26-
}
27-
28-
@media (prefers-color-scheme: dark) {
29-
:root {
30-
/* Dark Mode colors */
31-
--initial-bg-color: #0F0F0F; /* Dark Gray */
32-
--initial-text-color: #E7E7E7; /* Light Gray */
33-
}
34-
}
35-
36-
/* Apply initial landing page colors and hide content */
37-
body {
38-
background-color: var(--initial-bg-color);
39-
color: var(--initial-text-color);
40-
opacity: 0; /* Hidden by default */
41-
visibility: hidden;
42-
transition: opacity 0.3s ease-in-out; /* Smooth fade-in */
43-
min-height: 100vh; /* Ensures the body always takes at least the full viewport height */
44-
margin: 0; /* Remove default body margin */
45-
display: flex;
46-
flex-direction: column;
47-
justify-content: center;
48-
align-items: center;
49-
font-family: sans-serif; /* Basic font for initial load */
50-
}
51-
52-
/* Class to show the body content */
53-
body.loaded {
54-
opacity: 1;
55-
visibility: visible;
56-
}
57-
58-
/* Styles for the loading indicator (optional) */
59-
.loading-indicator {
60-
font-size: 2em;
61-
text-align: center;
62-
}
63-
64-
/* Original Scalar styles (ensure these are applied after initial hide) */
65-
.custom-header {
66-
height: var(--scalar-custom-header-height);
67-
background-color: var(--scalar-background-1);
68-
box-shadow: inset 0 -1px 0 var(--scalar-border-color);
69-
color: var(--scalar-color-1);
70-
font-size: var(--scalar-font-size-2);
71-
/* Increased padding on left and right for more space */
72-
padding: 0 36px; /* Increased from 18px */
73-
position: sticky;
74-
justify-content: space-between;
75-
top: 0;
76-
z-index: 100;
77-
width: 100%; /* Ensure header spans full width */
78-
box-sizing: border-box; /* Include padding in the width calculation */
79-
}
80-
.custom-header,
81-
.custom-header nav {
82-
display: flex;
83-
align-items: center;
84-
gap: 18px;
85-
font-size: var(--scalar-font-size-3);
86-
}
87-
.custom-header a:hover {
88-
color: var(--scalar-color-2);
89-
}
90-
91-
/* If the script targets a specific container, give it a min-height */
92-
/* This is still useful even if hidden, to reserve space when shown */
93-
#app {
94-
min-height: 500px; /* Adjust as needed based on expected content height */
95-
width: 100%; /* Ensure app container spans full width */
96-
}
97-
</style>
98-
<link rel="preload" href="https://cdn.jsdelivr.net/npm/@scalar/api-reference" as="script" />
99-
</head>
100-
101-
<body>
102-
<div class="loading-indicator">
103-
Loading API Documentation...
104-
</div>
105-
106-
<header class="custom-header scalar-app" style="display: none;">
107-
<b>ACM @ UIUC</b>
108-
<nav>
109-
<a href="https://acm.illinois.edu">Home</a>
110-
<a href="https://core.acm.illinois.edu">Management Portal</a>
111-
</nav>
112-
</header>
113-
<div id="app" style="display: none;"></div>
114-
115-
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
116-
117-
<script>
118-
function initializeAndShowPage() {
119-
// Hide the initial loading indicator
120-
document.querySelector('.loading-indicator').style.display = 'none';
121-
122-
// Show the actual header and app container
123-
document.querySelector('.custom-header').style.display = 'flex';
124-
document.getElementById('app').style.display = 'block';
125-
126-
Scalar.createApiReference('#app', {
127-
url: '/docs/openapi.json',
128-
});
129-
130-
// Add a class to the body to make it visible and apply full styles
131-
document.body.classList.add('loaded');
132-
}
133-
134-
// Check if Scalar is already defined, or wait for it to load
135-
if (typeof Scalar !== 'undefined' && typeof Scalar.createApiReference === 'function') {
136-
initializeAndShowPage();
137-
} else {
138-
document.addEventListener('DOMContentLoaded', initializeAndShowPage);
139-
}
140-
</script>
141-
</body>
142-
</html>
143-
`;
5+
import { docsHtml } from "./docs.js";
1446
/**
1457
* Generates and saves Swagger/OpenAPI specification files.
1468
*/
@@ -157,7 +19,7 @@ async function createSwaggerFiles() {
15719
const yamlSpec = app.swagger({ yaml: true });
15820
await writeFile(path.join(outputDir, "openapi.json"), jsonSpec);
15921
await writeFile(path.join(outputDir, "openapi.yaml"), yamlSpec);
160-
await writeFile(path.join(outputDir, "index.html"), html);
22+
await writeFile(path.join(outputDir, "index.html"), docsHtml);
16123

16224
console.log(`✅ Swagger files successfully generated in ${outputDir}`);
16325
await app.close();

‎src/api/docs.ts

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
export const docsHtml = `
2+
<!doctype html>
3+
<html>
4+
<head>
5+
<title>Core API Documentation | ACM @ UIUC</title>
6+
<meta charset="utf-8" />
7+
<meta
8+
name="viewport"
9+
content="width=device-width, initial-scale=1" />
10+
<meta property="og:title" content="Core API Documentation | ACM @ UIUC" />
11+
<meta property="og:description" content="The ACM @ UIUC Core API provides services for managing chapter operations." />
12+
<meta property="description" content="The ACM @ UIUC Core API provides services for managing chapter operations." />
13+
<meta property="og:image" content="https://static.acm.illinois.edu/square-blue.png" />
14+
<meta property="og:url" content="https://core.acm.illinois.edu/docs" />
15+
<style>
16+
:root {
17+
--scalar-custom-header-height: 50px;
18+
/* Default colors (Light Mode) */
19+
--initial-bg-color: #FFFFFF; /* White */
20+
--initial-text-color: #2A2F45; /* Black */
21+
}
22+
23+
@media (prefers-color-scheme: dark) {
24+
:root {
25+
/* Dark Mode colors */
26+
--initial-bg-color: #0F0F0F; /* Dark Gray */
27+
--initial-text-color: #E7E7E7; /* Light Gray */
28+
}
29+
}
30+
31+
/* Apply initial landing page colors and hide content */
32+
body {
33+
background-color: var(--initial-bg-color);
34+
color: var(--initial-text-color);
35+
opacity: 0; /* Hidden by default */
36+
visibility: hidden;
37+
transition: opacity 0.3s ease-in-out; /* Smooth fade-in */
38+
min-height: 100vh; /* Ensures the body always takes at least the full viewport height */
39+
margin: 0; /* Remove default body margin */
40+
display: flex;
41+
flex-direction: column;
42+
justify-content: center;
43+
align-items: center;
44+
font-family: sans-serif; /* Basic font for initial load */
45+
}
46+
47+
/* Class to show the body content */
48+
body.loaded {
49+
opacity: 1;
50+
visibility: visible;
51+
}
52+
53+
/* Styles for the loading indicator (optional) */
54+
.loading-indicator {
55+
font-size: 2em;
56+
text-align: center;
57+
}
58+
59+
/* Original Scalar styles (ensure these are applied after initial hide) */
60+
.custom-header {
61+
height: var(--scalar-custom-header-height);
62+
background-color: var(--scalar-background-1);
63+
box-shadow: inset 0 -1px 0 var(--scalar-border-color);
64+
color: var(--scalar-color-1);
65+
font-size: var(--scalar-font-size-2);
66+
/* Increased padding on left and right for more space */
67+
padding: 0 36px; /* Increased from 18px */
68+
position: sticky;
69+
justify-content: space-between;
70+
top: 0;
71+
z-index: 100;
72+
width: 100%; /* Ensure header spans full width */
73+
box-sizing: border-box; /* Include padding in the width calculation */
74+
}
75+
.custom-header,
76+
.custom-header nav {
77+
display: flex;
78+
align-items: center;
79+
gap: 18px;
80+
font-size: var(--scalar-font-size-3);
81+
}
82+
.custom-header a:hover {
83+
color: var(--scalar-color-2);
84+
}
85+
86+
/* If the script targets a specific container, give it a min-height */
87+
/* This is still useful even if hidden, to reserve space when shown */
88+
#app {
89+
min-height: 500px; /* Adjust as needed based on expected content height */
90+
width: 100%; /* Ensure app container spans full width */
91+
}
92+
</style>
93+
<link rel="preload" href="https://cdn.jsdelivr.net/npm/@scalar/api-reference" as="script" />
94+
</head>
95+
96+
<body>
97+
<div class="loading-indicator">
98+
Loading API Documentation...
99+
</div>
100+
101+
<header class="custom-header scalar-app" style="display: none;">
102+
<b>ACM @ UIUC</b>
103+
<nav>
104+
<a href="https://acm.illinois.edu">Home</a>
105+
<a href="https://core.acm.illinois.edu">Management Portal</a>
106+
</nav>
107+
</header>
108+
<div id="app" style="display: none;"></div>
109+
110+
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
111+
112+
<script>
113+
function initializeAndShowPage() {
114+
// Hide the initial loading indicator
115+
document.querySelector('.loading-indicator').style.display = 'none';
116+
117+
// Show the actual header and app container
118+
document.querySelector('.custom-header').style.display = 'flex';
119+
document.getElementById('app').style.display = 'block';
120+
121+
Scalar.createApiReference('#app', {
122+
url: '/docs/openapi.json',
123+
});
124+
125+
// Add a class to the body to make it visible and apply full styles
126+
document.body.classList.add('loaded');
127+
}
128+
129+
// Check if Scalar is already defined, or wait for it to load
130+
if (typeof Scalar !== 'undefined' && typeof Scalar.createApiReference === 'function') {
131+
initializeAndShowPage();
132+
} else {
133+
document.addEventListener('DOMContentLoaded', initializeAndShowPage);
134+
}
135+
</script>
136+
</body>
137+
</html>
138+
`;

0 commit comments

Comments
 (0)