@rapidoc/vitepress 0.1.0 → 0.1.2

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/README.md CHANGED
@@ -19,7 +19,7 @@ export default withRapidoc(
19
19
  themeConfig: {
20
20
  sidebar: [
21
21
  { text: "Guide", items: [{ text: "Getting started", link: "/" }] },
22
- { text: "Pets API", items: await rapidocSidebar("./openapi.yaml", "/api") },
22
+ { text: "Pets API", items: await rapidocSidebar({ spec: "./openapi.yaml", uiPath: "/api" }) },
23
23
  ],
24
24
  },
25
25
  }),
@@ -47,7 +47,7 @@ The reference is at `/api`. `layout: page` gives it the full content width.
47
47
  ## What you get
48
48
 
49
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.
50
+ - **Operations in the sidebar**: `rapidocSidebar({ spec, uiPath })` returns an overview link and a group per tag with a link per operation. Each shows its HTTP method (GET, POST, DEL) in RapiDoc's colours, and deprecated operations are struck through. An operation link is a section of the page (`/api#list-pets`), so moving between operations does not reload it.
51
51
  - **No request for the spec**: the documents in `apis` are read at build time and shipped with the page's script.
52
52
  - **Try it and OAuth**: the console works as in RapiDoc; the OAuth return page is written to `rapidoc/oauth-receiver.html`.
53
53
 
@@ -55,14 +55,24 @@ The reference is at `/api`. `layout: page` gives it the full content width.
55
55
 
56
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
57
 
58
- **`rapidocSidebar(spec, link, { collapsed?, root? })`** returns sidebar items for one API.
58
+ **`rapidocSidebar({ spec, uiPath, ... })`** returns sidebar items for one API.
59
+
60
+ | Option | Default | |
61
+ | :---------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | `spec` | required | The OpenAPI document: a JSON or YAML file (relative to `root`), a URL, or the object. It is read when the site is built |
63
+ | `uiPath` | required | URL path of the page that shows the reference, for example `/api`. Operation links point to sections of it |
64
+ | `methods` | `"as-colored-text"` | How each operation's HTTP method is shown: `"as-colored-text"`, `"as-plain-text"`, `"as-colored-block"`, or `false` for no method. Deprecated operations are struck through either way |
65
+ | `collapsed` | | `true` starts the tag groups collapsed |
66
+ | `root` | the working directory | Folder a relative `spec` file is resolved from |
67
+
68
+ The form of version 0.1, `rapidocSidebar(spec, link, options)`, still works.
59
69
 
60
70
  **`<RapidocReference>`** props:
61
71
 
62
72
  | Prop | |
63
73
  | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64
74
  | `api` | A name from `apis` |
65
- | `spec` | The OpenAPI document itself, instead of `api` |
75
+ | `spec` | The OpenAPI document as an object, instead of `api` |
66
76
  | `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
77
 
68
78
  ## Notes
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rapidoc/vitepress",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "RapiDoc for VitePress: OpenAPI reference pages inside your VitePress site, with the operations in the sidebar",
5
5
  "keywords": [
6
6
  "api documentation",
@@ -44,9 +44,9 @@
44
44
  "test": "node --test tests/**/*.test.js"
45
45
  },
46
46
  "dependencies": {
47
- "@rapidoc/embed": "^0.2.0",
48
- "@rapidoc/prerender": "^0.1.5",
49
- "rapidoc": "^12.2.1",
47
+ "@rapidoc/embed": "^0.3.1",
48
+ "@rapidoc/prerender": "^0.2.0",
49
+ "rapidoc": "^13.0.0",
50
50
  "yaml": "^2.9.1"
51
51
  },
52
52
  "devDependencies": {
package/src/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import type { UserConfig, DefaultTheme } from "vitepress";
2
+ import type { SidebarMethods } from "@rapidoc/embed";
2
3
 
3
4
  export interface WithRapidocOptions {
4
5
  /** 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. */
@@ -13,7 +14,27 @@ export declare function withRapidoc<T extends UserConfig<any>>(
13
14
  options?: WithRapidocOptions,
14
15
  ): T;
15
16
 
17
+ export interface RapidocSidebarOptions {
18
+ /** The OpenAPI document: a file (JSON or YAML, relative to `root`), a URL or the object. Read when the site is built. */
19
+ spec: string | object;
20
+ /** The URL path of the page that shows the API, for example `/api`. */
21
+ uiPath: string;
22
+ /**
23
+ * How each operation's HTTP method is shown, with the values of `<rapi-doc>`'s `show-method-in-nav-bar`:
24
+ * `"as-colored-text"` (default), `"as-plain-text"`, `"as-colored-block"`, or `false` for none.
25
+ */
26
+ methods?: SidebarMethods;
27
+ /** Start the tag groups collapsed. */
28
+ collapsed?: boolean;
29
+ /** Folder that a relative `spec` starts from. Default: the working directory. */
30
+ root?: string;
31
+ }
32
+
16
33
  /** Sidebar items for one API: an overview link, then a group per tag with a link per operation. */
34
+ export declare function rapidocSidebar(
35
+ options: RapidocSidebarOptions,
36
+ ): Promise<DefaultTheme.SidebarItem[]>;
37
+ /** @deprecated The form of version 0.1; pass one options object. */
17
38
  export declare function rapidocSidebar(
18
39
  spec: string | object,
19
40
  link: string,
package/src/index.js CHANGED
@@ -4,7 +4,14 @@
4
4
  import fs from "node:fs";
5
5
  import path from "node:path";
6
6
  import { parse } from "yaml";
7
- import { renderOAuthReceiverPage } from "@rapidoc/embed";
7
+ import {
8
+ escapeHtml,
9
+ methodLabel,
10
+ operationClass,
11
+ renderOAuthReceiverPage,
12
+ sidebarCss,
13
+ sidebarMethods,
14
+ } from "@rapidoc/embed";
8
15
  import { getSpecNavigation } from "@rapidoc/prerender";
9
16
 
10
17
  const VIRTUAL_ID = "virtual:rapidoc-vitepress";
@@ -38,14 +45,60 @@ export async function loadSpec(spec, root = process.cwd()) {
38
45
 
39
46
  const operationLabel = (operation) => operation.summary || `${operation.method} ${operation.path}`;
40
47
 
48
+ /**
49
+ * VitePress writes a sidebar item's text as HTML and offers no class for the item, so the method label
50
+ * is an element inside the text, and the text itself is escaped here.
51
+ */
52
+ function operationText(operation, methods) {
53
+ const method = methods === "false" ? "" : methodLabel(operation.method);
54
+ const label = method
55
+ ? `<span class="${operationClass(operation, methods)}">${method}</span>`
56
+ : "";
57
+ const text = escapeHtml(operationLabel(operation));
58
+ return operation.deprecated
59
+ ? `${label}<span class="rapidoc-op-text--deprecated" title="Deprecated">${text}</span>`
60
+ : `${label}${text}`;
61
+ }
62
+
63
+ /** The method in front of each operation link, in RapiDoc's colours, and deprecated ones struck through. */
64
+ export const SIDEBAR_CSS = sidebarCss({
65
+ label: (className) => `.VPSidebar .${className}`,
66
+ text: () => ".VPSidebar .rapidoc-op-text--deprecated",
67
+ dark: ".dark",
68
+ });
69
+
41
70
  /**
42
71
  * 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]
72
+ * link per operation. Links point into the API's page (`<uiPath>#<operation id>`).
73
+ *
74
+ * await rapidocSidebar({ spec: "./openapi.yaml", uiPath: "/api" })
75
+ *
76
+ * @param {object} options
77
+ * @param {string | object} options.spec a file (relative to `root`, default the working directory), a URL
78
+ * or the document. Read when the site is built.
79
+ * @param {string} options.uiPath the URL path of the page that shows the API, for example `/api`
80
+ * @param {boolean | string} [options.methods] how each operation's HTTP method is shown:
81
+ * "as-colored-text" (default), "as-plain-text", "as-colored-block", or false for none
82
+ * @param {boolean} [options.collapsed] start the tag groups collapsed
83
+ * @param {string} [options.root]
84
+ *
85
+ * Version 0.1 took `(spec, link, options)`; that form still works.
47
86
  */
48
- export async function rapidocSidebar(spec, link, options = {}) {
87
+ export async function rapidocSidebar(first, second, third = {}) {
88
+ // One options object has `spec` and no `openapi` key; an OpenAPI document given positionally has the latter
89
+ const named =
90
+ second === undefined &&
91
+ first &&
92
+ typeof first === "object" &&
93
+ "spec" in first &&
94
+ !("openapi" in first);
95
+ const options = named ? first : { ...third, spec: first, uiPath: second };
96
+ const { spec } = options;
97
+ const link = options.uiPath ?? options.path;
98
+ if (typeof link !== "string" || link === "") {
99
+ throw new TypeError('@rapidoc/vitepress: rapidocSidebar needs `uiPath`, for example "/api"');
100
+ }
101
+ const methods = sidebarMethods(options.methods);
49
102
  const document = await loadSpec(spec, options.root);
50
103
  const navigation = await getSpecNavigation(structuredClone(document));
51
104
  const tags = navigation.tagGroups.length
@@ -56,10 +109,10 @@ export async function rapidocSidebar(spec, link, options = {}) {
56
109
  for (const tag of tags) {
57
110
  if (tag.paths.length === 0) continue;
58
111
  items.push({
59
- text: tag.displayName || tag.name,
112
+ text: escapeHtml(tag.displayName || tag.name),
60
113
  ...(options.collapsed === undefined ? {} : { collapsed: options.collapsed }),
61
114
  items: tag.paths.map((operation) => ({
62
- text: operationLabel(operation),
115
+ text: operationText(operation, methods),
63
116
  link: `${link}#${operation.elementId}`,
64
117
  })),
65
118
  });
@@ -110,6 +163,8 @@ export function withRapidoc(config = {}, options = {}) {
110
163
  const noExternal = config.vite?.ssr?.noExternal;
111
164
  return {
112
165
  ...config,
166
+ // the sidebar is on every page, so the styles of its method labels are too
167
+ head: [...(config.head ?? []), ["style", {}, SIDEBAR_CSS]],
113
168
  vue: {
114
169
  ...config.vue,
115
170
  template: {