Skip to content

Commit 89951e8

Browse files
jstirnamanjstirnaman
committed
WIP(api): hide rapidoc sidebar, add API _index page, replace rapidoc CDN with package from npm and js.Build
1 parent c68f852 commit 89951e8

File tree

9 files changed

+1032
-84
lines changed

9 files changed

+1032
-84
lines changed

‎api-docs/scripts/create-pages.js

Lines changed: 88 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ const { execSync } = require('child_process');
66
const path = require('path');
77
const fs = require('fs');
88
const yaml = require('js-yaml');
9+
const { create } = require('domain');
910

1011
// Calculate the relative paths
1112
const DOCS_ROOT = process.env.DOCS_ROOT || '.';
@@ -50,34 +51,95 @@ function getPathGroups(openapi) {
5051
return pathGroups;
5152
}
5253

54+
const CONFIG = {
55+
apis: [
56+
{
57+
name: 'cloud-v2',
58+
menu_name: 'influxdb_cloud',
59+
menu:
60+
{
61+
parent: 'INFLUXDB HTTP API',
62+
weight: 0,
63+
},
64+
// Source OpenAPI spec file
65+
spec_file: path.join(DOCS_ROOT, '/api-docs/cloud/v2/ref.yml'),
66+
// Target content directory for generated endpoint spec pages
67+
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2/yaml'),
68+
// Target content directory for generated .md pages
69+
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2'),
70+
},
71+
{
72+
name: 'oss-v2',
73+
menu_name: 'influxdb_v2',
74+
menu:
75+
{
76+
parent: 'INFLUXDB HTTP API',
77+
weight: 0,
78+
},
79+
spec_file: path.join(DOCS_ROOT, '/api-docs/v2/ref.yml'),
80+
// Target content directory for generated endpoint spec pages
81+
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2/yaml'),
82+
// Target content directory for generated .md pages
83+
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2'),
84+
}
85+
]
86+
}
87+
88+
function createIndexPage(spec, api) {
89+
90+
const menu = {...api.menu, name: spec.info.title};
91+
const pageParams = {
92+
title: spec.info.title,
93+
description: spec.info.description,
94+
menu: {},
95+
};
96+
pageParams.menu[api.menu_name] = menu;
97+
98+
let frontMatter = JSON.stringify(pageParams);
99+
let page = frontMatter.concat('\n\n', spec.info.description, '\n\n', '{{< children >}}', '\n\n');
100+
101+
const pagePath = path.join(api.pages_dir, '_index.md');
102+
fs.writeFileSync(pagePath, page);
103+
console.log(`Created: ${pagePath}`);
104+
}
105+
106+
function createPathGroupPage(pathGroup, pathSpec, api) {
107+
pathSpec['x-pathGroupTitle'] = `${pathGroup}\n${spec.info.title}`;
108+
pathSpec['x-pathGroup'] = pathGroup;
109+
110+
const pageParams = {
111+
type: 'api',
112+
title: pathSpec['x-pathGroupTitle'],
113+
description: pathSpec.info.description,
114+
api: {
115+
part_of: api.spec_file,
116+
spec: JSON.stringify(pathSpec),
117+
},
118+
menu: {},
119+
}
120+
121+
const menu = {
122+
parent: spec.info.title,
123+
weight: 1,
124+
name: pathGroup
125+
};
126+
127+
pageParams.menu[api.menu_name] = menu;
128+
129+
let frontMatter = JSON.stringify(pageParams);
130+
131+
const pageName = `${pathGroup.replaceAll('/', '-').replace(/^-/, '')}`;
132+
const pagePath = path.join(api.pages_dir, `${pageName}.md`);
133+
fs.writeFileSync(pagePath, frontMatter);
134+
console.log(`Created: ${pagePath}`);
135+
}
136+
53137
function main() {
54138
/**
55139
* Configure the product specs to generate markdown files for.
56140
*/
57-
const config = {
58-
dataDir: path.join(DOCS_ROOT, '/data/api/influxdb'),
59-
apis: [
60-
{
61-
name: 'cloud-v2',
62-
menu: 'influxdb_cloud',
63-
// Source OpenAPI spec file
64-
spec_file: path.join(DOCS_ROOT, '/api-docs/cloud/v2/ref.yml'),
65-
// Target content directory for generated endpoint spec pages
66-
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2/yaml'),
67-
// Target content directory for generated .md pages
68-
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2'),
69-
},
70-
{
71-
name: 'oss-v2',
72-
menu: 'influxdb_v2',
73-
spec_file: path.join(DOCS_ROOT, '/api-docs/v2/ref.yml'),
74-
// Target content directory for generated endpoint spec pages
75-
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2/yaml'),
76-
// Target content directory for generated .md pages
77-
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2'),
78-
}
79-
]
80-
}
141+
142+
let config = CONFIG;
81143

82144
config.apis.forEach(api => {
83145
// Execute the getswagger.sh script to fetch and bundle the configured spec.
@@ -93,35 +155,12 @@ function main() {
93155
fs.mkdirSync(api.pages_dir, { recursive: true });
94156
};
95157

158+
createIndexPage(spec, api);
96159
Object.keys(pathGroups).forEach( pathGroup => {
97160
// Deep copy the spec object
98161
let pathSpec = JSON.parse(JSON.stringify(spec));
99162
pathSpec.paths = pathGroups[pathGroup];
100-
pathSpec['x-pathGroupTitle'] = `${pathGroup}\n${spec.info.title}`;
101-
pathSpec['x-pathGroup'] = pathGroup;
102-
103-
const pageParams = {
104-
type: 'api',
105-
title: pathSpec['x-pathGroupTitle'],
106-
description: pathSpec.info.description,
107-
api: {
108-
part_of: api.spec_file,
109-
spec: JSON.stringify(pathSpec),
110-
},
111-
}
112-
pageParams.menu = {};
113-
pageParams.menu[api.menu] = {
114-
parent: 'INFLUXDB HTTP API',
115-
weight: 1,
116-
name: pathGroup
117-
};
118-
119-
let frontMatter = JSON.stringify(pageParams);
120-
121-
const pageName = `${pathGroup.replaceAll('/', '-').replace(/^-/, '')}`;
122-
const pagePath = path.join(api.pages_dir, `${pageName}.md`);
123-
fs.writeFileSync(pagePath, frontMatter);
124-
console.log(`Created: ${pagePath}`);
163+
createPathGroupPage(pathGroup, pathSpec, api);
125164
});
126165
});
127166
}

‎api-docs/scripts/validate-spec.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ function validate() {
3030

3131
// Create a Spectral ruleset file
3232
// Spectral is a flexible JSON/YAML linter, formatter, and style checker for OpenAPI v2, v3.0, v3.1, and AsyncAPI v2.0.
33+
// For rule examples, see https://apistylebook.stoplight.io/docs/stoplight-style-guide/
3334
execCommand(`npx @stoplight/spectral-cli lint ${spec} --ruleset ./api-docs/.spectral.yaml`); // --ruleset myruleset.yaml
3435

3536
}

‎assets/js/api-doc/index.js

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import 'rapidoc';
2+
3+
function getUserPreferredUrl() {
4+
const urlName = window.getPreference && window.getPreference('influxdb_url');
5+
return getUrls()[urlName] || (window.placeholderUrls && window.placeholderUrls['oss']);
6+
}
7+
8+
export function apiDocComponent() {
9+
window.addEventListener('DOMContentLoaded', (event) => {
10+
const rapidocEl = document.getElementById('api-doc');
11+
if(rapidocEl === null) return;
12+
const apiServer = getUserPreferredUrl();
13+
rapidocEl.addEventListener('spec-loaded', (e) => {
14+
rapidocEl.setApiServer(apiServer);
15+
});
16+
const spec = JSON.parse(rapidocEl.dataset.openapiSpec);
17+
rapidocEl.loadSpec(spec);
18+
});
19+
}
20+
21+
apiDocComponent();

‎assets/js/main.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// assets/js/main.js
2+
import { apiDocComponent } from "./api-doc";
3+
4+
export { apiDocComponent };

‎assets/jsconfig.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"compilerOptions": {
3+
"baseUrl": ".",
4+
"paths": {
5+
"*": [
6+
"*"
7+
]
8+
}
9+
}
10+
}

‎layouts/api/single.html

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,32 @@
66
{{ partial "sidebar.html" . }}
77
<div class="content-wrapper">
88
<api-ref class="col-12 col-md-9 col-xl-8" role="main">
9-
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
10-
<h2>{{ .Params.title }}</h2>
11-
12-
<rapi-doc
13-
id="api-doc"
14-
data-openapi-partof = "{{ .Params.api.part_of }}"
15-
data-openapi-spec = "{{ .Params.api.spec }}"
16-
regular-font="Open Sans" mono-font="Roboto Mono" show-header="false"
17-
bg-color="#ffffff" text-color="" nav-bg-color="#fafafa" nav-text-color=""
18-
nav-hover-bg-color="#ffebea" nav-hover-text-color="#9b0700"
19-
nav-accent-color="" primary-color="#F63C41" theme="light"
20-
css-classes="col-12 col-md-9 col-xl-8"
21-
> </rapi-doc>
22-
<script>
23-
window.addEventListener('DOMContentLoaded', (event) => {
24-
const rapidocEl = document.getElementById('api-doc');
25-
rapidocEl.addEventListener('spec-loaded', (e) => {
26-
rapidocEl.setApiServer(globalThis.origin + "/api");
27-
// Sets the server to http://localhost:8080/api
28-
// you must have defined this server in your spec
29-
});
30-
const spec = JSON.parse(rapidocEl.dataset.openapiSpec);
31-
rapidocEl.loadSpec(spec);
32-
});
33-
</script>
9+
<div>
10+
<!-- For render-style=read you should try to provide height of rapi-doc element as it needs to calculate scroll positions-->
11+
<rapi-doc
12+
id="api-doc"
13+
allow-authentication="false"
14+
allow-search="true"
15+
bg-color="#ffffff"
16+
css-classes="col-12 col-md-9 col-xl-8"
17+
data-openapi-partof = "{{ .Params.api.part_of }}"
18+
data-openapi-spec = "{{ .Params.api.spec }}"
19+
default-api-server=""
20+
mono-font="Roboto Mono"
21+
nav-accent-color=""
22+
nav-bg-color="#fafafa"
23+
nav-hover-bg-color="#ffebea"
24+
nav-hover-text-color="#9b0700"
25+
nav-text-color=""
26+
primary-color="#F63C41"
27+
regular-font="Open Sans"
28+
render-style="view"
29+
show-header="false"
30+
show-info="false"
31+
style="height:100vh; width:100%"
32+
text-color=""
33+
theme="light"></rapi-doc>
34+
</div>
3435
</api-ref>
3536
<div class="copyright">© {{ now.Year }} InfluxData, Inc.</div>
3637
</div>

‎layouts/partials/header.html

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,7 @@
2626
<meta name="Copyright" content="InfluxData Inc." />
2727
</head>
2828
<body class='{{if ne $product nil}}{{ $product }}{{ else }}home{{ end }}{{ if in $currentVersion "v1" }} v1{{ end }}'>
29+
<!-- Bundle main.js JavaScript modules-->
30+
{{ $mainJs := resources.Get "js/main.js" | js.Build }}
31+
<script src="{{ $mainJs.RelPermalink }}"></script>
2932
{{ if not hugo.IsServer }}{{ partial "header/google-analytics-body.html" }}{{ end }}

‎package.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@
1717
"axios": "^1.7.4",
1818
"hugo-data-to-pages": "https://github.com/jstirnaman/hugo-data-to-pages",
1919
"hugo-extended": "^0.134.2",
20-
"js-yaml": "^4.1.0"
20+
"js-yaml": "^4.1.0",
21+
"rapidoc": "^9.3.6"
2122
},
2223
"scripts": {
2324
"lint": "LEFTHOOK_EXCLUDE=test lefthook run pre-commit && lefthook run pre-push",

0 commit comments

Comments
 (0)