Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(api-ref): Uplift API reference docs: #5595

Draft
wants to merge 14 commits into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
WIP(api): hide rapidoc sidebar, add API _index page, replace rapidoc …
…CDN with package from npm and js.Build
  • Loading branch information
jstirnaman committed Nov 5, 2024
commit b2ef303baa54d4b7ca56690e417161b71aa0837a
137 changes: 88 additions & 49 deletions api-docs/scripts/create-pages.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ const { execSync } = require('child_process');
const path = require('path');
const fs = require('fs');
const yaml = require('js-yaml');
const { create } = require('domain');

// Calculate the relative paths
const DOCS_ROOT = process.env.DOCS_ROOT || '.';
Expand Down Expand Up @@ -50,34 +51,95 @@ function getPathGroups(openapi) {
return pathGroups;
}

const CONFIG = {
apis: [
{
name: 'cloud-v2',
menu_name: 'influxdb_cloud',
menu:
{
parent: 'INFLUXDB HTTP API',
weight: 0,
},
// Source OpenAPI spec file
spec_file: path.join(DOCS_ROOT, '/api-docs/cloud/v2/ref.yml'),
// Target content directory for generated endpoint spec pages
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2/yaml'),
// Target content directory for generated .md pages
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2'),
},
{
name: 'oss-v2',
menu_name: 'influxdb_v2',
menu:
{
parent: 'INFLUXDB HTTP API',
weight: 0,
},
spec_file: path.join(DOCS_ROOT, '/api-docs/v2/ref.yml'),
// Target content directory for generated endpoint spec pages
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2/yaml'),
// Target content directory for generated .md pages
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2'),
}
]
}

function createIndexPage(spec, api) {

const menu = {...api.menu, name: spec.info.title};
const pageParams = {
title: spec.info.title,
description: spec.info.description,
menu: {},
};
pageParams.menu[api.menu_name] = menu;

let frontMatter = JSON.stringify(pageParams);
let page = frontMatter.concat('\n\n', spec.info.description, '\n\n', '{{< children >}}', '\n\n');

const pagePath = path.join(api.pages_dir, '_index.md');
fs.writeFileSync(pagePath, page);
console.log(`Created: ${pagePath}`);
}

function createPathGroupPage(pathGroup, pathSpec, api) {
pathSpec['x-pathGroupTitle'] = `${pathGroup}\n${spec.info.title}`;
pathSpec['x-pathGroup'] = pathGroup;

const pageParams = {
type: 'api',
title: pathSpec['x-pathGroupTitle'],
description: pathSpec.info.description,
api: {
part_of: api.spec_file,
spec: JSON.stringify(pathSpec),
},
menu: {},
}

const menu = {
parent: spec.info.title,
weight: 1,
name: pathGroup
};

pageParams.menu[api.menu_name] = menu;

let frontMatter = JSON.stringify(pageParams);

const pageName = `${pathGroup.replaceAll('/', '-').replace(/^-/, '')}`;
const pagePath = path.join(api.pages_dir, `${pageName}.md`);
fs.writeFileSync(pagePath, frontMatter);
console.log(`Created: ${pagePath}`);
}

function main() {
/**
* Configure the product specs to generate markdown files for.
*/
const config = {
dataDir: path.join(DOCS_ROOT, '/data/api/influxdb'),
apis: [
{
name: 'cloud-v2',
menu: 'influxdb_cloud',
// Source OpenAPI spec file
spec_file: path.join(DOCS_ROOT, '/api-docs/cloud/v2/ref.yml'),
// Target content directory for generated endpoint spec pages
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2/yaml'),
// Target content directory for generated .md pages
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/cloud/api/v2'),
},
{
name: 'oss-v2',
menu: 'influxdb_v2',
spec_file: path.join(DOCS_ROOT, '/api-docs/v2/ref.yml'),
// Target content directory for generated endpoint spec pages
// endpoints_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2/yaml'),
// Target content directory for generated .md pages
pages_dir: path.join(DOCS_ROOT, '/content/influxdb/v2/api/v2'),
}
]
}

let config = CONFIG;

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

createIndexPage(spec, api);
Object.keys(pathGroups).forEach( pathGroup => {
// Deep copy the spec object
let pathSpec = JSON.parse(JSON.stringify(spec));
pathSpec.paths = pathGroups[pathGroup];
pathSpec['x-pathGroupTitle'] = `${pathGroup}\n${spec.info.title}`;
pathSpec['x-pathGroup'] = pathGroup;

const pageParams = {
type: 'api',
title: pathSpec['x-pathGroupTitle'],
description: pathSpec.info.description,
api: {
part_of: api.spec_file,
spec: JSON.stringify(pathSpec),
},
}
pageParams.menu = {};
pageParams.menu[api.menu] = {
parent: 'INFLUXDB HTTP API',
weight: 1,
name: pathGroup
};

let frontMatter = JSON.stringify(pageParams);

const pageName = `${pathGroup.replaceAll('/', '-').replace(/^-/, '')}`;
const pagePath = path.join(api.pages_dir, `${pageName}.md`);
fs.writeFileSync(pagePath, frontMatter);
console.log(`Created: ${pagePath}`);
createPathGroupPage(pathGroup, pathSpec, api);
});
});
}
Expand Down
1 change: 1 addition & 0 deletions api-docs/scripts/validate-spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ function validate() {

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

}
Expand Down
21 changes: 21 additions & 0 deletions assets/js/api-doc/index.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import 'rapidoc';

function getUserPreferredUrl() {
const urlName = window.getPreference && window.getPreference('influxdb_url');
return getUrls()[urlName] || (window.placeholderUrls && window.placeholderUrls['oss']);
}

export function apiDocComponent() {
window.addEventListener('DOMContentLoaded', (event) => {
const rapidocEl = document.getElementById('api-doc');
if(rapidocEl === null) return;
const apiServer = getUserPreferredUrl();
rapidocEl.addEventListener('spec-loaded', (e) => {
rapidocEl.setApiServer(apiServer);
});
const spec = JSON.parse(rapidocEl.dataset.openapiSpec);
rapidocEl.loadSpec(spec);
});
}

apiDocComponent();
4 changes: 4 additions & 0 deletions assets/js/main.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
// assets/js/main.js
import { apiDocComponent } from "./api-doc";

export { apiDocComponent };
51 changes: 26 additions & 25 deletions layouts/api/single.html
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,32 @@
{{ partial "sidebar.html" . }}
<div class="content-wrapper">
<api-ref class="col-12 col-md-9 col-xl-8" role="main">
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
<h2>{{ .Params.title }}</h2>

<rapi-doc
id="api-doc"
data-openapi-partof = "{{ .Params.api.part_of }}"
data-openapi-spec = "{{ .Params.api.spec }}"
regular-font="Open Sans" mono-font="Roboto Mono" show-header="false"
bg-color="#ffffff" text-color="" nav-bg-color="#fafafa" nav-text-color=""
nav-hover-bg-color="#ffebea" nav-hover-text-color="#9b0700"
nav-accent-color="" primary-color="#F63C41" theme="light"
css-classes="col-12 col-md-9 col-xl-8"
> </rapi-doc>
<script>
window.addEventListener('DOMContentLoaded', (event) => {
const rapidocEl = document.getElementById('api-doc');
rapidocEl.addEventListener('spec-loaded', (e) => {
rapidocEl.setApiServer(globalThis.origin + "/api");
// Sets the server to http://localhost:8080/api
// you must have defined this server in your spec
});
const spec = JSON.parse(rapidocEl.dataset.openapiSpec);
rapidocEl.loadSpec(spec);
});
</script>
<div>
<!-- For render-style=read you should try to provide height of rapi-doc element as it needs to calculate scroll positions-->
<rapi-doc
id="api-doc"
allow-authentication="false"
allow-search="true"
bg-color="#ffffff"
css-classes="col-12 col-md-9 col-xl-8"
data-openapi-partof = "{{ .Params.api.part_of }}"
data-openapi-spec = "{{ .Params.api.spec }}"
default-api-server=""
mono-font="Roboto Mono"
nav-accent-color=""
nav-bg-color="#fafafa"
nav-hover-bg-color="#ffebea"
nav-hover-text-color="#9b0700"
nav-text-color=""
primary-color="#F63C41"
regular-font="Open Sans"
render-style="view"
show-header="false"
show-info="false"
style="height:100vh; width:100%"
text-color=""
theme="light"></rapi-doc>
</div>
</api-ref>
<div class="copyright">© {{ now.Year }} InfluxData, Inc.</div>
</div>
Expand Down
3 changes: 3 additions & 0 deletions layouts/partials/header.html
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,7 @@
<meta name="Copyright" content="InfluxData Inc." />
</head>
<body class='{{if ne $product nil}}{{ $product }}{{ else }}home{{ end }}{{ if in $currentVersion "v1" }} v1{{ end }}'>
<!-- Bundle main.js JavaScript modules-->
{{ $mainJs := resources.Get "js/main.js" | js.Build }}
<script src="{{ $mainJs.RelPermalink }}"></script>
{{ if not hugo.IsServer }}{{ partial "header/google-analytics-body.html" }}{{ end }}
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@
"axios": "^1.7.4",
"hugo-data-to-pages": "https://github.com/jstirnaman/hugo-data-to-pages",
"hugo-extended": "^0.134.2",
"js-yaml": "^4.1.0"
"js-yaml": "^4.1.0",
"rapidoc": "^9.3.6"
},
"scripts": {
"lint": "LEFTHOOK_EXCLUDE=test lefthook run pre-commit && lefthook run pre-push",
Expand Down
Loading