@rapidoc/starlight 0.1.1 → 0.1.3

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
@@ -16,13 +16,13 @@ export default defineConfig({
16
16
  integrations: [
17
17
  starlight({
18
18
  title: "My docs",
19
- plugins: [starlightRapidoc({ path: "/api", spec: "./openapi.yaml" })],
19
+ plugins: [starlightRapidoc({ uiPath: "/api", spec: "./openapi.yaml" })],
20
20
  }),
21
21
  ],
22
22
  });
23
23
  ```
24
24
 
25
- The reference is at `/api`. The sidebar gets a group named after the API, with an overview link and a link for every operation, grouped by tag.
25
+ The reference is at `/api`. The sidebar gets a group named after the API, with an overview link and a link for every operation, grouped by tag. Each operation shows its HTTP method (GET, POST, DEL) in RapiDoc's colours, and deprecated operations are struck through.
26
26
 
27
27
  ## What you get
28
28
 
@@ -30,20 +30,20 @@ The reference is at `/api`. The sidebar gets a group named after the API, with a
30
30
  - **The site's colours**: the reference follows Starlight's light and dark themes and sits on its background.
31
31
  - **One page per API**: an operation link is a section of that page (`/api/#list-pets`), so moving between operations does not reload it.
32
32
  - **No request for the spec**: the document is read at build time and written into the page.
33
- - **Try it and OAuth**: the console works as in RapiDoc; the OAuth return page is built at `{path}/oauth-receiver/`.
33
+ - **Try it and OAuth**: the console works as in RapiDoc; the OAuth return page is built at `{uiPath}/oauth-receiver/`.
34
34
 
35
35
  ## Options
36
36
 
37
- | Option | Default | |
38
- | :-------- | :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
39
- | `path` | required | Where the reference page is served, for example `/api` |
40
- | `spec` | required | The OpenAPI document: a JSON or YAML file (relative to the project root), a URL, or the object. It is read when the site is built |
41
- | `title` | the document's `info.title` | Page title |
42
- | `label` | the title | Sidebar group label |
43
- | `options` | | [Attributes of `<rapi-doc>`](https://rapidocui.com/api/), in kebab-case or camelCase: `{ allowTry: false, theme: "jade" }`. They win over the plugin's own |
44
- | `sidebar` | | `false` adds nothing to the sidebar (link to the page yourself); `{ collapsed: true }` starts the tag groups collapsed |
37
+ | Option | Default | |
38
+ | :-------- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
39
+ | `uiPath` | required | URL path of the reference page within the site, for example `/api`. `path` is its old name, still read |
40
+ | `spec` | required | The OpenAPI document: a JSON or YAML file (relative to the project root), a URL, or the object. Whichever it is, it is read when the site is built and written into the page; the browser makes no request for it |
41
+ | `title` | the document's `info.title` | Page title |
42
+ | `label` | the title | Sidebar group label |
43
+ | `options` | | [Attributes of `<rapi-doc>`](https://rapidocui.com/api/), in kebab-case or camelCase: `{ allowTry: false, theme: "jade" }`. They win over the plugin's own |
44
+ | `sidebar` | | `false` adds nothing to the sidebar (link to the page yourself). `{ collapsed: true }` starts the tag groups collapsed. `{ methods }` sets how each operation's HTTP method is shown: `"as-colored-text"` (default), `"as-plain-text"`, `"as-colored-block"`, or `false` for no method. Deprecated operations are struck through either way |
45
45
 
46
- For several APIs, pass `{ apis: [{ path, spec }, { path, spec }] }`.
46
+ For several APIs, pass `{ apis: [{ uiPath, spec }, { uiPath, spec }] }`.
47
47
 
48
48
  The sidebar group is added after your own `sidebar` entries. If your config has no `sidebar`, Starlight generates one from your files; adding the API group replaces that generated sidebar, so list your pages in `sidebar` too, for example with `{ label: "Guides", autogenerate: { directory: "guides" } }`.
49
49
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rapidoc/starlight",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "RapiDoc for Starlight: OpenAPI reference pages inside your Starlight docs, with the operations in the sidebar",
5
5
  "keywords": [
6
6
  "api documentation",
@@ -41,9 +41,9 @@
41
41
  "test": "node --test tests/**/*.test.js"
42
42
  },
43
43
  "dependencies": {
44
- "@rapidoc/embed": "^0.2.0",
45
- "@rapidoc/prerender": "^0.1.5",
46
- "rapidoc": "^12.2.1",
44
+ "@rapidoc/embed": "^0.3.1",
45
+ "@rapidoc/prerender": "^0.2.0",
46
+ "rapidoc": "^13.0.0",
47
47
  "yaml": "^2.9.1"
48
48
  },
49
49
  "peerDependencies": {
package/src/ApiPage.astro CHANGED
@@ -6,7 +6,7 @@ import { apis } from 'virtual:rapidoc-starlight';
6
6
 
7
7
  const base = import.meta.env.BASE_URL.replace(/\/+$/, '');
8
8
  const pathname = Astro.url.pathname.slice(base.length).replace(/\/+$/, '');
9
- const api = apis.find((candidate) => candidate.path === pathname);
9
+ const api = apis.find((candidate) => candidate.uiPath === pathname);
10
10
  if (!api) throw new Error(`@rapidoc/starlight: no API is configured at ${Astro.url.pathname}`);
11
11
  ---
12
12
 
package/src/apis.js CHANGED
@@ -5,6 +5,7 @@ import fs from "node:fs";
5
5
  import path from "node:path";
6
6
  import { parse } from "yaml";
7
7
  import { normalizePath, toAttributes, inlineJson } from "@rapidoc/embed/core";
8
+ import { operationClass, sidebarCss, sidebarMethods } from "@rapidoc/embed/sidebar";
8
9
  import { getSpecNavigation } from "@rapidoc/prerender";
9
10
 
10
11
  /**
@@ -50,11 +51,12 @@ export async function loadSpec(spec, root) {
50
51
  return document;
51
52
  }
52
53
 
53
- /** `/docs/api/` → `/docs/api`; a path is required, and the site root is not allowed (Starlight owns it). */
54
- function apiPath(value) {
55
- const normalized = normalizePath(value ?? "");
54
+ /** `/docs/api/` → `/docs/api`; `uiPath` is required, and the site root is not allowed (Starlight owns it). */
55
+ function apiUiPath(api) {
56
+ // `path` was this option's name in 0.1
57
+ const normalized = normalizePath(api.uiPath ?? api.path ?? "");
56
58
  if (normalized === "") {
57
- throw new TypeError('@rapidoc/starlight: each API needs `path`, for example "/api"');
59
+ throw new TypeError('@rapidoc/starlight: each API needs `uiPath`, for example "/api"');
58
60
  }
59
61
  return normalized;
60
62
  }
@@ -65,14 +67,28 @@ export function pageUrl(base, pagePath, trailingSlash = "ignore") {
65
67
  return `${prefix}${pagePath}${trailingSlash === "never" ? "" : "/"}`;
66
68
  }
67
69
 
70
+ /** The method in front of each operation link, in RapiDoc's colours, and deprecated ones struck through. */
71
+ export const SIDEBAR_CSS = sidebarCss({
72
+ label: (className) => `a.${className}::before`,
73
+ text: (className) => `a.${className} > span`,
74
+ dark: ":root[data-theme='dark']",
75
+ // Starlight fills the current item with its accent colour
76
+ active: "a.rapidoc-op[aria-current='page']::before",
77
+ });
78
+
68
79
  const operationLabel = (operation) => operation.summary || `${operation.method} ${operation.path}`;
69
80
 
70
- function tagItems(tag, href) {
81
+ function tagItems(tag, href, methods) {
71
82
  return tag.paths.map((operation) => ({
72
83
  label: operationLabel(operation),
73
84
  link: `${href}#${operation.elementId}`,
74
- ...(operation.deprecated ? { badge: { text: "deprecated", variant: "caution" } } : {}),
75
- attrs: { "data-rapidoc-op": operation.elementId, "data-method": operation.method },
85
+ attrs: {
86
+ "data-rapidoc-op": operation.elementId,
87
+ "data-method": operation.method,
88
+ // the method label and the deprecated mark are drawn by SIDEBAR_CSS from these classes
89
+ class: operationClass(operation, methods),
90
+ ...(operation.deprecated ? { title: "Deprecated" } : {}),
91
+ },
76
92
  }));
77
93
  }
78
94
 
@@ -90,7 +106,7 @@ export function sidebarGroup(api, navigation, href) {
90
106
  items.push({
91
107
  label: tag.displayName || tag.name,
92
108
  collapsed: api.sidebar?.collapsed ?? false,
93
- items: tagItems(tag, href),
109
+ items: tagItems(tag, href, api.sidebar?.methods),
94
110
  });
95
111
  }
96
112
  return { label: api.label ?? api.title, collapsed: false, items };
@@ -108,16 +124,18 @@ export async function resolveApis(userOptions, site) {
108
124
  ? [userOptions]
109
125
  : [];
110
126
  if (list.length === 0) {
111
- throw new TypeError("@rapidoc/starlight: give at least one API: { path, spec }");
127
+ throw new TypeError("@rapidoc/starlight: give at least one API: { uiPath, spec }");
112
128
  }
113
129
  const apis = [];
114
130
  const sidebar = [];
115
131
  const seen = new Set();
116
132
  for (const given of list) {
117
- const pagePath = apiPath(given.path);
118
- if (seen.has(pagePath))
119
- throw new TypeError(`@rapidoc/starlight: two APIs use the path ${pagePath}`);
133
+ const pagePath = apiUiPath(given);
134
+ if (seen.has(pagePath)) {
135
+ throw new TypeError(`@rapidoc/starlight: two APIs use the uiPath ${pagePath}`);
136
+ }
120
137
  seen.add(pagePath);
138
+ if (given.sidebar) sidebarMethods(given.sidebar.methods); // fail on a wrong value before building
121
139
 
122
140
  const spec = await loadSpec(given.spec, site.root);
123
141
  const navigation = await getSpecNavigation(structuredClone(spec));
@@ -128,7 +146,7 @@ export async function resolveApis(userOptions, site) {
128
146
  // The contract's attribute rules (names, booleans, sorting); the page defaults first, the user's last
129
147
  const attributes = Object.fromEntries(
130
148
  toAttributes({
131
- path: pagePath,
149
+ uiPath: pagePath,
132
150
  options: {
133
151
  ...PAGE_ATTRIBUTES,
134
152
  "oauth-receiver": receiver,
@@ -138,7 +156,7 @@ export async function resolveApis(userOptions, site) {
138
156
  }),
139
157
  );
140
158
 
141
- const api = { path: pagePath, title, attributes, specJson: inlineJson(spec) };
159
+ const api = { uiPath: pagePath, title, attributes, specJson: inlineJson(spec) };
142
160
  apis.push(api);
143
161
  if (given.sidebar !== false) {
144
162
  sidebar.push(sidebarGroup({ ...given, title }, navigation, href));
package/src/index.d.ts CHANGED
@@ -1,9 +1,11 @@
1
1
  import type { StarlightPlugin } from "@astrojs/starlight/types";
2
- import type { RapiDocOptions } from "@rapidoc/embed";
2
+ import type { RapiDocOptions, SidebarMethods } from "@rapidoc/embed";
3
3
 
4
4
  export interface StarlightRapidocApi {
5
- /** Where the reference page is served, for example `/api`. */
6
- path: string;
5
+ /** The URL path of the reference page, for example `/api`. Required. */
6
+ uiPath?: string;
7
+ /** @deprecated Renamed to `uiPath`. */
8
+ path?: string;
7
9
  /** The OpenAPI document: a file (JSON or YAML, relative to the project root), a URL, or the object. Read at build time. */
8
10
  spec: string | object;
9
11
  /** Page title. Default: the document's `info.title`. */
@@ -12,8 +14,12 @@ export interface StarlightRapidocApi {
12
14
  label?: string;
13
15
  /** Attributes of `<rapi-doc>`, in kebab-case or camelCase. They win over the plugin's own. */
14
16
  options?: RapiDocOptions;
15
- /** `false` adds nothing to the sidebar; `{ collapsed: true }` starts the tag groups collapsed. */
16
- sidebar?: false | { collapsed?: boolean };
17
+ /**
18
+ * `false` adds nothing to the sidebar. `collapsed: true` starts the tag groups collapsed. `methods` is
19
+ * how each operation's HTTP method is shown, with the values of `<rapi-doc>`'s `show-method-in-nav-bar`:
20
+ * `"as-colored-text"` (default), `"as-plain-text"`, `"as-colored-block"`, or `false` for none.
21
+ */
22
+ sidebar?: false | { collapsed?: boolean; methods?: SidebarMethods };
17
23
  }
18
24
 
19
25
  export type StarlightRapidocOptions = StarlightRapidocApi | { apis: StarlightRapidocApi[] };
package/src/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // @rapidoc/starlight: a Starlight plugin that adds an API reference page per OpenAPI document, drawn by
2
2
  // <rapi-doc> inside Starlight's layout, with the API's tags and operations in Starlight's sidebar.
3
3
  import { fileURLToPath } from "node:url";
4
- import { resolveApis } from "./apis.js";
4
+ import { resolveApis, SIDEBAR_CSS } from "./apis.js";
5
5
 
6
6
  const VIRTUAL_ID = "virtual:rapidoc-starlight";
7
7
  const entry = (file) => fileURLToPath(new URL(file, import.meta.url));
@@ -13,9 +13,13 @@ function rapidocIntegration(apis) {
13
13
  hooks: {
14
14
  "astro:config:setup"({ injectRoute, updateConfig }) {
15
15
  for (const api of apis) {
16
- injectRoute({ pattern: api.path, entrypoint: entry("./ApiPage.astro"), prerender: true });
17
16
  injectRoute({
18
- pattern: `${api.path}/oauth-receiver`,
17
+ pattern: api.uiPath,
18
+ entrypoint: entry("./ApiPage.astro"),
19
+ prerender: true,
20
+ });
21
+ injectRoute({
22
+ pattern: `${api.uiPath}/oauth-receiver`,
19
23
  entrypoint: entry("./OAuthReceiver.astro"),
20
24
  prerender: true,
21
25
  });
@@ -40,7 +44,7 @@ function rapidocIntegration(apis) {
40
44
  }
41
45
 
42
46
  /**
43
- * `starlight({ plugins: [starlightRapidoc({ path: "/api", spec: "./openapi.yaml" })] })`, or
47
+ * `starlight({ plugins: [starlightRapidoc({ uiPath: "/api", spec: "./openapi.yaml" })] })`, or
44
48
  * `starlightRapidoc({ apis: [...] })` for several APIs.
45
49
  */
46
50
  export default function starlightRapidoc(userOptions) {
@@ -54,7 +58,11 @@ export default function starlightRapidoc(userOptions) {
54
58
  trailingSlash: astroConfig.trailingSlash,
55
59
  });
56
60
  if (sidebar.length > 0) {
57
- updateConfig({ sidebar: [...(config.sidebar ?? []), ...sidebar] });
61
+ updateConfig({
62
+ sidebar: [...(config.sidebar ?? []), ...sidebar],
63
+ // the sidebar is on every page, so its styles are too
64
+ head: [...(config.head ?? []), { tag: "style", content: SIDEBAR_CSS }],
65
+ });
58
66
  }
59
67
  addIntegration(rapidocIntegration(apis));
60
68
  },