@rapidoc/starlight 0.1.1 → 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 +12 -12
- package/package.json +2 -2
- package/src/ApiPage.astro +1 -1
- package/src/apis.js +32 -14
- package/src/index.d.ts +11 -5
- package/src/index.js +13 -5
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({
|
|
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 `{
|
|
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
|
-
| `
|
|
40
|
-
| `spec` | required | The OpenAPI document: a JSON or YAML file (relative to the project root), a URL, or the object.
|
|
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)
|
|
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: [{
|
|
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.
|
|
3
|
+
"version": "0.1.2",
|
|
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,7 +41,7 @@
|
|
|
41
41
|
"test": "node --test tests/**/*.test.js"
|
|
42
42
|
},
|
|
43
43
|
"dependencies": {
|
|
44
|
-
"@rapidoc/embed": "^0.
|
|
44
|
+
"@rapidoc/embed": "^0.3.0",
|
|
45
45
|
"@rapidoc/prerender": "^0.1.5",
|
|
46
46
|
"rapidoc": "^12.2.1",
|
|
47
47
|
"yaml": "^2.9.1"
|
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.
|
|
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`;
|
|
54
|
-
function
|
|
55
|
-
|
|
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 `
|
|
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
|
-
|
|
75
|
-
|
|
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: {
|
|
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 =
|
|
118
|
-
if (seen.has(pagePath))
|
|
119
|
-
throw new TypeError(`@rapidoc/starlight: two APIs use the
|
|
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
|
-
|
|
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 = {
|
|
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
|
-
/**
|
|
6
|
-
|
|
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
|
-
/**
|
|
16
|
-
|
|
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:
|
|
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({
|
|
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({
|
|
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
|
},
|