@rapidoc/vitepress 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.txt +22 -0
- package/README.md +72 -2
- package/package.json +59 -4
- package/src/client.d.ts +16 -0
- package/src/client.js +95 -0
- package/src/index.d.ts +26 -0
- package/src/index.js +146 -0
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2022 Mrinmoy Majumdar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
6
|
+
a copy of this software and associated documentation files (the
|
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
|
11
|
+
the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be
|
|
14
|
+
included in all copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,73 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @rapidoc/vitepress
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Adds API reference pages to a [VitePress](https://vitepress.dev) site. An OpenAPI document becomes a page drawn by [RapiDoc](https://rapidocui.com) inside your theme, with the API's tags and operations in the sidebar.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install @rapidoc/vitepress
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
**1. Wrap the config** and name your OpenAPI documents:
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
// .vitepress/config.mjs
|
|
13
|
+
import { defineConfig } from "vitepress";
|
|
14
|
+
import { withRapidoc, rapidocSidebar } from "@rapidoc/vitepress";
|
|
15
|
+
|
|
16
|
+
export default withRapidoc(
|
|
17
|
+
defineConfig({
|
|
18
|
+
title: "My docs",
|
|
19
|
+
themeConfig: {
|
|
20
|
+
sidebar: [
|
|
21
|
+
{ text: "Guide", items: [{ text: "Getting started", link: "/" }] },
|
|
22
|
+
{ text: "Pets API", items: await rapidocSidebar("./openapi.yaml", "/api") },
|
|
23
|
+
],
|
|
24
|
+
},
|
|
25
|
+
}),
|
|
26
|
+
{ apis: { pets: "./openapi.yaml" } },
|
|
27
|
+
);
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
**2. Add the page**, for example `api.md`:
|
|
31
|
+
|
|
32
|
+
```md
|
|
33
|
+
---
|
|
34
|
+
title: Pets API
|
|
35
|
+
layout: page
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
<script setup>
|
|
39
|
+
import { RapidocReference } from "@rapidoc/vitepress/client";
|
|
40
|
+
</script>
|
|
41
|
+
|
|
42
|
+
<RapidocReference api="pets" />
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The reference is at `/api`. `layout: page` gives it the full content width.
|
|
46
|
+
|
|
47
|
+
## What you get
|
|
48
|
+
|
|
49
|
+
- **Your theme's layout**: its nav, sidebar and dark-mode switch stay; RapiDoc's own header and sidebar are off, and the reference follows the theme's light and dark modes.
|
|
50
|
+
- **Operations in the sidebar**: `rapidocSidebar(spec, link)` returns an overview link and a group per tag with a link per operation. An operation link is a section of the page (`/api#list-pets`), so moving between operations does not reload it.
|
|
51
|
+
- **No request for the spec**: the documents in `apis` are read at build time and shipped with the page's script.
|
|
52
|
+
- **Try it and OAuth**: the console works as in RapiDoc; the OAuth return page is written to `rapidoc/oauth-receiver.html`.
|
|
53
|
+
|
|
54
|
+
## API
|
|
55
|
+
|
|
56
|
+
**`withRapidoc(config, { apis, root? })`** wraps the VitePress config. `apis` maps a name to an OpenAPI document: a JSON or YAML file (relative to `root`, default the working directory), a URL or an object. It also lets you write `<rapi-doc-mini>` directly in Markdown.
|
|
57
|
+
|
|
58
|
+
**`rapidocSidebar(spec, link, { collapsed?, root? })`** returns sidebar items for one API.
|
|
59
|
+
|
|
60
|
+
**`<RapidocReference>`** props:
|
|
61
|
+
|
|
62
|
+
| Prop | |
|
|
63
|
+
| :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| `api` | A name from `apis` |
|
|
65
|
+
| `spec` | The OpenAPI document itself, instead of `api` |
|
|
66
|
+
| `options` | [Attributes of `<rapi-doc>`](https://rapidocui.com/api/), in kebab-case or camelCase: `:options="{ allowTry: false, theme: 'jade' }"`. They win over the component's own |
|
|
67
|
+
|
|
68
|
+
## Notes
|
|
69
|
+
|
|
70
|
+
- The component sets `render-style="focused"`, `show-header="false"`, `show-side-nav="false"`, `auto-height="true"` and `color-scheme="auto"`. Change any of them through `options`.
|
|
71
|
+
- The OAuth return page loads the pinned `rapidoc` version from jsDelivr, because the site's own copy of the bundle has a hashed file name.
|
|
72
|
+
- API pages are not in the local search index: their content is drawn in the browser.
|
|
73
|
+
- Tested on VitePress 1.6 and 2.0 alpha. MIT.
|
package/package.json
CHANGED
|
@@ -1,6 +1,61 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rapidoc/vitepress",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "RapiDoc for VitePress: OpenAPI reference pages inside your VitePress site, with the operations in the sidebar",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"api documentation",
|
|
7
|
+
"openapi",
|
|
8
|
+
"rapidoc",
|
|
9
|
+
"rapidoc-integration",
|
|
10
|
+
"vitepress",
|
|
11
|
+
"vitepress-plugin"
|
|
12
|
+
],
|
|
13
|
+
"homepage": "https://rapidocui.com",
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/rapi-doc/RapiDoc/issues"
|
|
16
|
+
},
|
|
17
|
+
"license": "MIT",
|
|
18
|
+
"author": "Mrinmoy Majumdar <mrin9@yahoo.com>",
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/rapi-doc/RapiDoc.git",
|
|
22
|
+
"directory": "packages/rapidoc-vitepress"
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"src"
|
|
26
|
+
],
|
|
27
|
+
"type": "module",
|
|
28
|
+
"main": "./src/index.js",
|
|
29
|
+
"types": "./src/index.d.ts",
|
|
30
|
+
"exports": {
|
|
31
|
+
".": {
|
|
32
|
+
"types": "./src/index.d.ts",
|
|
33
|
+
"default": "./src/index.js"
|
|
34
|
+
},
|
|
35
|
+
"./client": {
|
|
36
|
+
"types": "./src/client.d.ts",
|
|
37
|
+
"default": "./src/client.js"
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
"publishConfig": {
|
|
41
|
+
"access": "public"
|
|
42
|
+
},
|
|
43
|
+
"scripts": {
|
|
44
|
+
"test": "node --test tests/**/*.test.js"
|
|
45
|
+
},
|
|
46
|
+
"dependencies": {
|
|
47
|
+
"@rapidoc/embed": "^0.1.0",
|
|
48
|
+
"@rapidoc/prerender": "^0.1.5",
|
|
49
|
+
"rapidoc": "^12.2.0",
|
|
50
|
+
"yaml": "^2.9.1"
|
|
51
|
+
},
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"vitepress": "2.0.0-alpha.21"
|
|
54
|
+
},
|
|
55
|
+
"peerDependencies": {
|
|
56
|
+
"vitepress": ">=1.0.0"
|
|
57
|
+
},
|
|
58
|
+
"engines": {
|
|
59
|
+
"node": ">=22.12.0"
|
|
60
|
+
}
|
|
61
|
+
}
|
package/src/client.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { DefineComponent } from "vue";
|
|
2
|
+
import type { RapiDocOptions } from "@rapidoc/embed";
|
|
3
|
+
|
|
4
|
+
/** Draws an API reference with `<rapi-doc>` in a VitePress page. */
|
|
5
|
+
export declare const RapidocReference: DefineComponent<{
|
|
6
|
+
/** Name of a document given to `withRapidoc({ apis })`. */
|
|
7
|
+
api?: string;
|
|
8
|
+
/** The OpenAPI document itself, instead of `api`. */
|
|
9
|
+
spec?: object;
|
|
10
|
+
/** Attributes of `<rapi-doc>`, in kebab-case or camelCase. */
|
|
11
|
+
options?: RapiDocOptions;
|
|
12
|
+
}>;
|
|
13
|
+
export default RapidocReference;
|
|
14
|
+
|
|
15
|
+
/** The attributes the component sets before `options`. */
|
|
16
|
+
export declare const PAGE_ATTRIBUTES: Record<string, string>;
|
package/src/client.js
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
// @rapidoc/vitepress/client: the component that draws an API reference in a VitePress page.
|
|
2
|
+
//
|
|
3
|
+
// <script setup>
|
|
4
|
+
// import { RapidocReference } from '@rapidoc/vitepress/client'
|
|
5
|
+
// </script>
|
|
6
|
+
//
|
|
7
|
+
// <RapidocReference api="pets" />
|
|
8
|
+
//
|
|
9
|
+
// `api` names a document given to `withRapidoc` in the config. The element is loaded in the browser only.
|
|
10
|
+
import { defineComponent, h, onMounted, onBeforeUnmount, ref, watch } from "vue";
|
|
11
|
+
import { useRoute, withBase } from "vitepress";
|
|
12
|
+
import { toAttributes } from "@rapidoc/embed/core";
|
|
13
|
+
import { specs, oauthReceiver } from "virtual:rapidoc-vitepress";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* How <rapi-doc> sits in a VitePress page: the theme's nav and sidebar replace its own, the page scrolls
|
|
17
|
+
* instead of the element, and its colours follow the theme's light and dark modes.
|
|
18
|
+
*/
|
|
19
|
+
export const PAGE_ATTRIBUTES = {
|
|
20
|
+
"render-style": "focused",
|
|
21
|
+
"show-header": "false",
|
|
22
|
+
"show-side-nav": "false",
|
|
23
|
+
"auto-height": "true",
|
|
24
|
+
"color-scheme": "auto",
|
|
25
|
+
"allow-spec-url-load": "false",
|
|
26
|
+
"allow-spec-file-load": "false",
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
export const RapidocReference = defineComponent({
|
|
30
|
+
name: "RapidocReference",
|
|
31
|
+
props: {
|
|
32
|
+
/** Name of a document given to `withRapidoc({ apis })`. */
|
|
33
|
+
api: { type: String, default: undefined },
|
|
34
|
+
/** The OpenAPI document itself, instead of `api`. */
|
|
35
|
+
spec: { type: Object, default: undefined },
|
|
36
|
+
/** Attributes of <rapi-doc>, in kebab-case or camelCase. They win over the component's own. */
|
|
37
|
+
options: { type: Object, default: () => ({}) },
|
|
38
|
+
},
|
|
39
|
+
setup(props) {
|
|
40
|
+
const element = ref(null);
|
|
41
|
+
const route = useRoute();
|
|
42
|
+
const document = () => props.spec ?? specs[props.api];
|
|
43
|
+
|
|
44
|
+
const attributes = () =>
|
|
45
|
+
Object.fromEntries(
|
|
46
|
+
toAttributes({
|
|
47
|
+
options: {
|
|
48
|
+
...PAGE_ATTRIBUTES,
|
|
49
|
+
"oauth-receiver": withBase(`/${oauthReceiver}`),
|
|
50
|
+
...props.options,
|
|
51
|
+
},
|
|
52
|
+
}),
|
|
53
|
+
);
|
|
54
|
+
|
|
55
|
+
const fromHash = () => decodeURIComponent(window.location.hash.slice(1));
|
|
56
|
+
// The sidebar's operation links only change the hash; VitePress handles them itself, so tell the element
|
|
57
|
+
const showHash = () => {
|
|
58
|
+
const id = fromHash();
|
|
59
|
+
if (id && element.value?.scrollToPath) element.value.scrollToPath(id);
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
onMounted(async () => {
|
|
63
|
+
if (!document()) {
|
|
64
|
+
throw new Error(
|
|
65
|
+
`@rapidoc/vitepress: no API named "${props.api}"; add it to withRapidoc({ apis }) in the config`,
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
await import("rapidoc");
|
|
69
|
+
await customElements.whenDefined("rapi-doc");
|
|
70
|
+
await element.value?.loadSpec(structuredClone(document()));
|
|
71
|
+
showHash();
|
|
72
|
+
window.addEventListener("hashchange", showHash);
|
|
73
|
+
});
|
|
74
|
+
onBeforeUnmount(() => window.removeEventListener("hashchange", showHash));
|
|
75
|
+
watch(
|
|
76
|
+
() => route.hash,
|
|
77
|
+
() => showHash(),
|
|
78
|
+
);
|
|
79
|
+
watch(
|
|
80
|
+
() => [props.api, props.spec],
|
|
81
|
+
() => element.value?.loadSpec?.(structuredClone(document())),
|
|
82
|
+
);
|
|
83
|
+
|
|
84
|
+
return () =>
|
|
85
|
+
h("rapi-doc", {
|
|
86
|
+
ref: element,
|
|
87
|
+
class: "rapidoc-vitepress",
|
|
88
|
+
// sit on the theme's own background, in both of its modes
|
|
89
|
+
style: "display:block;width:100%;min-height:60vh;--background:var(--vp-c-bg)",
|
|
90
|
+
...attributes(),
|
|
91
|
+
});
|
|
92
|
+
},
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
export default RapidocReference;
|
package/src/index.d.ts
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { UserConfig, DefaultTheme } from "vitepress";
|
|
2
|
+
|
|
3
|
+
export interface WithRapidocOptions {
|
|
4
|
+
/** The OpenAPI documents the pages show, by name: a file (JSON or YAML, relative to `root`), a URL or the object. Read at build time. */
|
|
5
|
+
apis?: Record<string, string | object>;
|
|
6
|
+
/** Folder that relative spec paths start from. Default: the working directory. */
|
|
7
|
+
root?: string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/** Wraps a VitePress config with what `<RapidocReference>` needs. */
|
|
11
|
+
export declare function withRapidoc<T extends UserConfig<any>>(
|
|
12
|
+
config?: T,
|
|
13
|
+
options?: WithRapidocOptions,
|
|
14
|
+
): T;
|
|
15
|
+
|
|
16
|
+
/** Sidebar items for one API: an overview link, then a group per tag with a link per operation. */
|
|
17
|
+
export declare function rapidocSidebar(
|
|
18
|
+
spec: string | object,
|
|
19
|
+
link: string,
|
|
20
|
+
options?: { root?: string; collapsed?: boolean },
|
|
21
|
+
): Promise<DefaultTheme.SidebarItem[]>;
|
|
22
|
+
|
|
23
|
+
export declare function loadSpec(spec: string | object, root?: string): Promise<object>;
|
|
24
|
+
|
|
25
|
+
/** Where the OAuth return page is served, under the site's base. */
|
|
26
|
+
export declare const OAUTH_RECEIVER_PATH: string;
|
package/src/index.js
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
// @rapidoc/vitepress, the config side (Node): `withRapidoc` adds what the site needs to draw an API
|
|
2
|
+
// reference with <rapi-doc>, and `rapidocSidebar` lists an API's operations for the theme's sidebar.
|
|
3
|
+
// The page itself is drawn by the component in ./client.js.
|
|
4
|
+
import fs from "node:fs";
|
|
5
|
+
import path from "node:path";
|
|
6
|
+
import { parse } from "yaml";
|
|
7
|
+
import { renderOAuthReceiverPage } from "@rapidoc/embed";
|
|
8
|
+
import { getSpecNavigation } from "@rapidoc/prerender";
|
|
9
|
+
|
|
10
|
+
const VIRTUAL_ID = "virtual:rapidoc-vitepress";
|
|
11
|
+
/** Where the OAuth return page is served, under the site's base. */
|
|
12
|
+
export const OAUTH_RECEIVER_PATH = "rapidoc/oauth-receiver.html";
|
|
13
|
+
|
|
14
|
+
const isUrl = (value) => /^https?:\/\//i.test(value);
|
|
15
|
+
|
|
16
|
+
/** The OpenAPI document as an object: from a file (JSON or YAML, relative to `root`), a URL or as given. */
|
|
17
|
+
export async function loadSpec(spec, root = process.cwd()) {
|
|
18
|
+
if (spec && typeof spec === "object") return spec;
|
|
19
|
+
if (typeof spec !== "string" || spec === "") {
|
|
20
|
+
throw new TypeError("@rapidoc/vitepress: a spec is a file path, a URL or an object");
|
|
21
|
+
}
|
|
22
|
+
let text;
|
|
23
|
+
if (isUrl(spec)) {
|
|
24
|
+
const response = await fetch(spec);
|
|
25
|
+
if (!response.ok) throw new Error(`@rapidoc/vitepress: ${spec} answered ${response.status}`);
|
|
26
|
+
text = await response.text();
|
|
27
|
+
} else {
|
|
28
|
+
const file = path.resolve(root, spec);
|
|
29
|
+
if (!fs.existsSync(file)) throw new Error(`@rapidoc/vitepress: spec file not found: ${file}`);
|
|
30
|
+
text = fs.readFileSync(file, "utf8");
|
|
31
|
+
}
|
|
32
|
+
const document = parse(text);
|
|
33
|
+
if (!document || typeof document !== "object") {
|
|
34
|
+
throw new Error(`@rapidoc/vitepress: ${spec} is not an OpenAPI document`);
|
|
35
|
+
}
|
|
36
|
+
return document;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const operationLabel = (operation) => operation.summary || `${operation.method} ${operation.path}`;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Sidebar items for one API, for `themeConfig.sidebar`: an overview link, then a group per tag with a
|
|
43
|
+
* link per operation. Links point into the API's page (`<link>#<operation id>`).
|
|
44
|
+
* @param {string | object} spec a file (relative to `options.root`, default the working directory), a URL or the document
|
|
45
|
+
* @param {string} link the page that shows the API, for example `/api`
|
|
46
|
+
* @param {{ root?: string, collapsed?: boolean }} [options]
|
|
47
|
+
*/
|
|
48
|
+
export async function rapidocSidebar(spec, link, options = {}) {
|
|
49
|
+
const document = await loadSpec(spec, options.root);
|
|
50
|
+
const navigation = await getSpecNavigation(structuredClone(document));
|
|
51
|
+
const tags = navigation.tagGroups.length
|
|
52
|
+
? [...navigation.tagGroups.flatMap((group) => group.tags), ...navigation.remainingTags]
|
|
53
|
+
: navigation.tags;
|
|
54
|
+
// #overview is the hash <rapi-doc> sets when it opens, so only one sidebar link is active at a time
|
|
55
|
+
const items = [{ text: "Overview", link: `${link}#overview` }];
|
|
56
|
+
for (const tag of tags) {
|
|
57
|
+
if (tag.paths.length === 0) continue;
|
|
58
|
+
items.push({
|
|
59
|
+
text: tag.displayName || tag.name,
|
|
60
|
+
...(options.collapsed === undefined ? {} : { collapsed: options.collapsed }),
|
|
61
|
+
items: tag.paths.map((operation) => ({
|
|
62
|
+
text: operationLabel(operation),
|
|
63
|
+
link: `${link}#${operation.elementId}`,
|
|
64
|
+
})),
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
return items;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The Vite plugin: the specs by name for the client component, and the OAuth return page in dev. */
|
|
71
|
+
function rapidocVitePlugin(apis, root) {
|
|
72
|
+
let base = "/";
|
|
73
|
+
return {
|
|
74
|
+
name: "rapidoc-vitepress",
|
|
75
|
+
configResolved(config) {
|
|
76
|
+
base = config.base;
|
|
77
|
+
},
|
|
78
|
+
resolveId: (id) => (id === VIRTUAL_ID ? `\0${VIRTUAL_ID}` : undefined),
|
|
79
|
+
async load(id) {
|
|
80
|
+
if (id !== `\0${VIRTUAL_ID}`) return undefined;
|
|
81
|
+
const specs = {};
|
|
82
|
+
for (const [name, spec] of Object.entries(apis)) {
|
|
83
|
+
specs[name] = await loadSpec(spec, root);
|
|
84
|
+
if (typeof spec === "string" && !isUrl(spec)) this.addWatchFile(path.resolve(root, spec));
|
|
85
|
+
}
|
|
86
|
+
return `export const specs = ${JSON.stringify(specs)};\nexport const oauthReceiver = ${JSON.stringify(OAUTH_RECEIVER_PATH)};`;
|
|
87
|
+
},
|
|
88
|
+
configureServer(server) {
|
|
89
|
+
server.middlewares.use((req, res, next) => {
|
|
90
|
+
if (req.url?.split("?")[0] !== `${base}${OAUTH_RECEIVER_PATH}`) return next();
|
|
91
|
+
res.setHeader("content-type", "text/html; charset=utf-8");
|
|
92
|
+
res.end(renderOAuthReceiverPage({ assets: "cdn" }));
|
|
93
|
+
});
|
|
94
|
+
},
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Wraps a VitePress config: `export default withRapidoc(defineConfig({ ... }), { apis: { pets: "./openapi.yaml" } })`.
|
|
100
|
+
* - `apis` names the OpenAPI documents the pages show (`<RapidocReference api="pets" />`); each is a file
|
|
101
|
+
* relative to the project root, a URL or an object, read at build time.
|
|
102
|
+
* - Tags starting with `rapi-` are left to the browser, so `<rapi-doc-mini>` can be written in Markdown.
|
|
103
|
+
* - The OAuth return page is written to `rapidoc/oauth-receiver.html`.
|
|
104
|
+
*/
|
|
105
|
+
export function withRapidoc(config = {}, options = {}) {
|
|
106
|
+
const apis = options.apis ?? {};
|
|
107
|
+
const root = options.root ?? process.cwd();
|
|
108
|
+
const userIsCustomElement = config.vue?.template?.compilerOptions?.isCustomElement;
|
|
109
|
+
const userBuildEnd = config.buildEnd;
|
|
110
|
+
const noExternal = config.vite?.ssr?.noExternal;
|
|
111
|
+
return {
|
|
112
|
+
...config,
|
|
113
|
+
vue: {
|
|
114
|
+
...config.vue,
|
|
115
|
+
template: {
|
|
116
|
+
...config.vue?.template,
|
|
117
|
+
compilerOptions: {
|
|
118
|
+
...config.vue?.template?.compilerOptions,
|
|
119
|
+
isCustomElement: (tag) => tag.startsWith("rapi-") || Boolean(userIsCustomElement?.(tag)),
|
|
120
|
+
},
|
|
121
|
+
},
|
|
122
|
+
},
|
|
123
|
+
vite: {
|
|
124
|
+
...config.vite,
|
|
125
|
+
plugins: [...(config.vite?.plugins ?? []), rapidocVitePlugin(apis, root)],
|
|
126
|
+
ssr: {
|
|
127
|
+
...config.vite?.ssr,
|
|
128
|
+
// The client component imports a virtual module, so it has to go through Vite on the server too
|
|
129
|
+
noExternal:
|
|
130
|
+
noExternal === true
|
|
131
|
+
? true
|
|
132
|
+
: [
|
|
133
|
+
...(Array.isArray(noExternal) ? noExternal : noExternal ? [noExternal] : []),
|
|
134
|
+
"@rapidoc/vitepress",
|
|
135
|
+
],
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
async buildEnd(siteConfig) {
|
|
139
|
+
await userBuildEnd?.(siteConfig);
|
|
140
|
+
const file = path.join(siteConfig.outDir, OAUTH_RECEIVER_PATH);
|
|
141
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
142
|
+
// The bundle the pages load is hashed by Vite, so this page loads the same rapidoc version from the CDN
|
|
143
|
+
fs.writeFileSync(file, renderOAuthReceiverPage({ assets: "cdn" }));
|
|
144
|
+
},
|
|
145
|
+
};
|
|
146
|
+
}
|