@alauda/doom 0.2.1 → 0.2.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/lib/cli/load-config.js +1 -1
- package/lib/plugins/api/index.js +6 -4
- package/lib/plugins/auto-sidebar/walk.js +1 -1
- package/lib/runtime/components/K8sCrd.d.ts +8 -1
- package/lib/runtime/components/K8sCrd.js +9 -3
- package/lib/runtime/components/OpenAPIPath.d.ts +12 -1
- package/lib/runtime/components/OpenAPIPath.js +20 -10
- package/lib/runtime/components/OpenAPIRef.d.ts +8 -2
- package/lib/runtime/components/OpenAPIRef.js +9 -13
- package/lib/runtime/components/Overview.js +1 -1
- package/lib/runtime/types.d.ts +1 -0
- package/lib/utils/types.d.ts +1 -0
- package/package.json +2 -1
package/lib/cli/load-config.js
CHANGED
package/lib/plugins/api/index.js
CHANGED
|
@@ -5,7 +5,7 @@ import { glob } from 'tinyglobby';
|
|
|
5
5
|
import { resolveStaticConfig } from '../../utils/index.js';
|
|
6
6
|
const crdsMap = {};
|
|
7
7
|
const openapisMap = {};
|
|
8
|
-
|
|
8
|
+
const shared = {};
|
|
9
9
|
export const apiPlugin = () => {
|
|
10
10
|
return {
|
|
11
11
|
name: 'doom-api',
|
|
@@ -14,7 +14,7 @@ export const apiPlugin = () => {
|
|
|
14
14
|
if (!config.api) {
|
|
15
15
|
return;
|
|
16
16
|
}
|
|
17
|
-
const { crds, openapis, references } = config.api;
|
|
17
|
+
const { crds, openapis, references, pathPrefix } = config.api;
|
|
18
18
|
if (crds) {
|
|
19
19
|
for (const file of await glob(crds, {
|
|
20
20
|
cwd: config.root,
|
|
@@ -39,12 +39,14 @@ export const apiPlugin = () => {
|
|
|
39
39
|
openapisMap[file] = doc;
|
|
40
40
|
}
|
|
41
41
|
}
|
|
42
|
-
|
|
42
|
+
shared.references = references;
|
|
43
|
+
shared.pathPrefix = pathPrefix;
|
|
43
44
|
},
|
|
44
45
|
extendPageData(pageData) {
|
|
45
46
|
pageData.crdsMap = crdsMap;
|
|
46
47
|
pageData.openapisMap = openapisMap;
|
|
47
|
-
pageData.references =
|
|
48
|
+
pageData.references = shared.references;
|
|
49
|
+
pageData.pathPrefix = shared.pathPrefix;
|
|
48
50
|
},
|
|
49
51
|
};
|
|
50
52
|
};
|
|
@@ -58,7 +58,7 @@ export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, exten
|
|
|
58
58
|
});
|
|
59
59
|
sideMeta = (await Promise.all(subItems.map(async (item) => {
|
|
60
60
|
// Fix https://github.com/web-infra-dev/rspress/issues/346
|
|
61
|
-
if (item === '_meta.json') {
|
|
61
|
+
if (item === '_meta.json' || item === 'assets') {
|
|
62
62
|
return null;
|
|
63
63
|
}
|
|
64
64
|
const stat = await fs.stat(path.join(workDir, item));
|
|
@@ -3,7 +3,14 @@
|
|
|
3
3
|
*/
|
|
4
4
|
import { OpenAPIV3_1 } from 'openapi-types';
|
|
5
5
|
export interface K8sCrdProps {
|
|
6
|
+
/**
|
|
7
|
+
* The `metadata.name` of the CustomResourceDefinition
|
|
8
|
+
*/
|
|
6
9
|
name: string;
|
|
10
|
+
/**
|
|
11
|
+
* The specific path to the CRD, otherwise the first matched will be used.
|
|
12
|
+
*/
|
|
13
|
+
crdPath?: string;
|
|
7
14
|
}
|
|
8
15
|
export declare const K8sCrdSchemaPart: ({ name, parent, schema: property, openAll, }: {
|
|
9
16
|
name: string;
|
|
@@ -15,5 +22,5 @@ export declare const K8sCrdSchema: ({ schema, version, }: {
|
|
|
15
22
|
schema: OpenAPIV3_1.SchemaObject;
|
|
16
23
|
version: string;
|
|
17
24
|
}) => import("react/jsx-runtime").JSX.Element;
|
|
18
|
-
export declare const K8sCrd: ({ name }: K8sCrdProps) => import("react/jsx-runtime").JSX.Element | null;
|
|
25
|
+
export declare const K8sCrd: ({ name, crdPath }: K8sCrdProps) => import("react/jsx-runtime").JSX.Element | null;
|
|
19
26
|
export default K8sCrd;
|
|
@@ -41,6 +41,7 @@ export const K8sCrdSchemaPart = ({ name, parent, schema: property, openAll, }) =
|
|
|
41
41
|
return (_jsx(_Fragment, { children: _jsxs(Directive, { type: "details", title: _jsxs(_Fragment, { children: [name, type && _jsx(X.code, { children: type }), required && _jsx(Badge, { children: "required" })] }), open: open, onToggle: onToggle, children: [_jsx(Markdown, { children: schema.description }), props &&
|
|
42
42
|
Object.entries(props).map(([name, subSchema]) => (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name)))] }) }));
|
|
43
43
|
};
|
|
44
|
+
const SKIPPED_PROPERTIES = ['apiVersion', 'kind', 'metadata'];
|
|
44
45
|
export const K8sCrdSchema = ({ schema, version, }) => {
|
|
45
46
|
const { description, properties } = schema;
|
|
46
47
|
const t = useTranslation();
|
|
@@ -51,11 +52,16 @@ export const K8sCrdSchema = ({ schema, version, }) => {
|
|
|
51
52
|
const collapseAll = useCallback(() => {
|
|
52
53
|
setOpenAll(false);
|
|
53
54
|
}, []);
|
|
54
|
-
return (_jsxs(_Fragment, { children: [_jsx(Markdown, { children: description }), _jsxs("div", { className: "flex items-center", children: [_jsxs("span", { children: [_jsx(X.code, { children: version }), _jsx(Badge, { children: "version" })] }), properties != null && (_jsxs("div", { className: "ml-auto", children: [_jsx(Button, { className: "doom-btn", type: "button", text: _jsxs("span", { onClick: collapseAll, children: ["- ", t('collapse_all')] }), size: "medium", theme: "alt" }), _jsx(Button, { className: "doom-btn ml-2", type: "button", text: _jsxs("span", { onClick: expandAll, children: ["+ ", t('expand_all')] }), size: "medium", theme: "alt" })] }))] }), properties == null ? (_jsx(Directive, { type: "warning", children: t('crd_no_schema') })) : (_jsx("div", { className: "doom-collapse-group", children: Object.entries(properties).map(([name, subSchema]) => (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name))) }))] }));
|
|
55
|
+
return (_jsxs(_Fragment, { children: [_jsx(Markdown, { children: description }), _jsxs("div", { className: "flex items-center", children: [_jsxs("span", { children: [_jsx(X.code, { children: version }), _jsx(Badge, { children: "version" })] }), properties != null && (_jsxs("div", { className: "ml-auto", children: [_jsx(Button, { className: "doom-btn", type: "button", text: _jsxs("span", { onClick: collapseAll, children: ["- ", t('collapse_all')] }), size: "medium", theme: "alt" }), _jsx(Button, { className: "doom-btn ml-2", type: "button", text: _jsxs("span", { onClick: expandAll, children: ["+ ", t('expand_all')] }), size: "medium", theme: "alt" })] }))] }), properties == null ? (_jsx(Directive, { type: "warning", children: t('crd_no_schema') })) : (_jsx("div", { className: "doom-collapse-group", children: Object.entries(properties).map(([name, subSchema]) => SKIPPED_PROPERTIES.includes(name) || (_jsx(K8sCrdSchemaPart, { name: name, parent: schema, schema: subSchema, openAll: openAll }, name))) }))] }));
|
|
55
56
|
};
|
|
56
|
-
export const K8sCrd = ({ name }) => {
|
|
57
|
+
export const K8sCrd = ({ name, crdPath }) => {
|
|
57
58
|
const { page } = usePageData();
|
|
58
|
-
const crd = useMemo(() => Object.
|
|
59
|
+
const [, crd] = useMemo(() => Object.entries(page.crdsMap || {}).find(([pathname, crd]) => {
|
|
60
|
+
if (crdPath && pathname !== crdPath) {
|
|
61
|
+
return false;
|
|
62
|
+
}
|
|
63
|
+
return crd.metadata.name === name;
|
|
64
|
+
}) || [], [page]);
|
|
59
65
|
if (!crd) {
|
|
60
66
|
console.error(`No CustomResourceDefinition found for ${name}`);
|
|
61
67
|
return null;
|
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
import { OpenAPIV3_1 } from 'openapi-types';
|
|
2
2
|
export interface OpenAPIPathProps {
|
|
3
|
+
/**
|
|
4
|
+
* The path under the OpenAPI schema `paths` definition.
|
|
5
|
+
*/
|
|
3
6
|
path: string;
|
|
7
|
+
/**
|
|
8
|
+
* The specific path to the OpenAPI schema, otherwise the first matched will be used.
|
|
9
|
+
*/
|
|
10
|
+
openapiPath?: string;
|
|
11
|
+
/**
|
|
12
|
+
* If you have a gateway which adds common path prefix, can be used to override global config level `pathPrefix`.
|
|
13
|
+
*/
|
|
14
|
+
pathPrefix?: string;
|
|
4
15
|
}
|
|
5
16
|
export declare const OpenAPIParameters: ({ parameters, openapi, }: {
|
|
6
17
|
parameters: Array<OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject>;
|
|
@@ -10,5 +21,5 @@ export declare const OpenAPIResponses: ({ responses, openapi, }: {
|
|
|
10
21
|
responses: OpenAPIV3_1.ResponsesObject;
|
|
11
22
|
openapi: OpenAPIV3_1.Document;
|
|
12
23
|
}) => import("react/jsx-runtime").JSX.Element;
|
|
13
|
-
export declare const OpenAPIPath: ({ path }: OpenAPIPathProps) => import("react/jsx-runtime").JSX.Element | null;
|
|
24
|
+
export declare const OpenAPIPath: ({ path, openapiPath: openapiPath_, pathPrefix: pathPrefix_, }: OpenAPIPathProps) => import("react/jsx-runtime").JSX.Element | null;
|
|
14
25
|
export default OpenAPIPath;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
|
|
2
2
|
import { usePageData } from '@rspress/core/runtime';
|
|
3
|
-
import { getCustomMDXComponent } from '@rspress/core/theme';
|
|
3
|
+
import { Badge, getCustomMDXComponent } from '@rspress/core/theme';
|
|
4
4
|
import BananaSlug from 'github-slugger';
|
|
5
5
|
import { OpenAPIV3 } from 'openapi-types';
|
|
6
6
|
import { useMemo } from 'react';
|
|
@@ -24,7 +24,7 @@ export const OpenAPIParameters = ({ parameters, openapi, }) => {
|
|
|
24
24
|
else if (type) {
|
|
25
25
|
typeNode = _jsx(RefLink, { "$ref": type.$ref });
|
|
26
26
|
}
|
|
27
|
-
return (_jsxs(X.li, { children: [_jsx(X.code, { children: paramObj.name }), "(", _jsxs("em", { children: ["in ", paramObj.in] }), "):", ' ', typeNode,
|
|
27
|
+
return (_jsxs(X.li, { children: [_jsx(X.code, { children: paramObj.name }), "(", _jsxs("em", { children: ["in ", paramObj.in] }), "):", ' ', typeNode, paramObj.required && _jsx(Badge, { children: "required" }), _jsx(Markdown, { children: paramObj.description })] }, index));
|
|
28
28
|
}) }));
|
|
29
29
|
};
|
|
30
30
|
export const OpenAPIResponses = ({ responses, openapi, }) => {
|
|
@@ -72,16 +72,21 @@ const getRefsForPath = (openapi, path, knownRefs) => {
|
|
|
72
72
|
}
|
|
73
73
|
return Array.from(refs);
|
|
74
74
|
};
|
|
75
|
-
export const OpenAPIPath = ({ path }) => {
|
|
75
|
+
export const OpenAPIPath = ({ path, openapiPath: openapiPath_, pathPrefix: pathPrefix_, }) => {
|
|
76
76
|
const { page } = usePageData();
|
|
77
|
+
const pathPrefix = pathPrefix_ ?? (page.pathPrefix || '');
|
|
77
78
|
const slugger = useMemo(() => new BananaSlug(), []);
|
|
78
|
-
const [pathItem, openapi, refs] = useMemo(() => {
|
|
79
|
-
for (const openapi of Object.
|
|
79
|
+
const [pathItem, openapi, openapiPath, refs] = useMemo(() => {
|
|
80
|
+
for (const [pathname, openapi] of Object.entries(page.openapisMap || {})) {
|
|
81
|
+
if (openapiPath_ && pathname !== openapiPath_) {
|
|
82
|
+
continue;
|
|
83
|
+
}
|
|
80
84
|
const pathItem = openapi.paths?.[path];
|
|
81
85
|
if (pathItem) {
|
|
82
86
|
return [
|
|
83
87
|
pathItem,
|
|
84
88
|
openapi,
|
|
89
|
+
pathname,
|
|
85
90
|
getRefsForPath(openapi, path, omitRoutePathRefs({
|
|
86
91
|
...page.references,
|
|
87
92
|
...DEFAULT_COMMON_REFS,
|
|
@@ -95,16 +100,21 @@ export const OpenAPIPath = ({ path }) => {
|
|
|
95
100
|
console.error(`No OpenAPI path definition found for ${path}`);
|
|
96
101
|
return null;
|
|
97
102
|
}
|
|
98
|
-
return (_jsxs(_Fragment, { children: [
|
|
103
|
+
return (_jsxs(_Fragment, { children: [_jsxs(HeadingTitle, { slugger: slugger, level: 2, children: [pathPrefix, path] }), pathItem.parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 3, children: "Common Parameters" }), _jsx(OpenAPIParameters, { parameters: pathItem.parameters, openapi: openapi })] })), Object.values(OpenAPIV3.HttpMethods).map((method) => {
|
|
99
104
|
if (!pathItem[method]) {
|
|
100
105
|
return null;
|
|
101
106
|
}
|
|
102
107
|
const { description, parameters, requestBody, responses, summary } = pathItem[method];
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
108
|
+
const requestBodyRef = requestBody &&
|
|
109
|
+
('$ref' in requestBody
|
|
110
|
+
? requestBody.$ref
|
|
111
|
+
: requestBody.content['application/json'].schema?.$ref);
|
|
112
|
+
const requestBodySchema = requestBodyRef
|
|
113
|
+
? resolveRef(openapi, requestBodyRef)
|
|
114
|
+
: undefined;
|
|
115
|
+
return (_jsxs(_Fragment, { children: [_jsxs(HeadingTitle, { slugger: slugger, level: 3, children: [_jsx(X.code, { children: method }), summary] }), _jsx(Markdown, { children: description }), parameters && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Parameters" }), _jsx(OpenAPIParameters, { parameters: parameters, openapi: openapi })] })), requestBodySchema && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Request Body" }), _jsxs(X.p, { children: [_jsx(RefLink, { "$ref": requestBodyRef }), requestBodySchema.required && _jsx(Badge, { children: "required" })] })] })), responses && (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slugger: slugger, level: 4, children: "Response" }), _jsx(OpenAPIResponses, { responses: responses, openapi: openapi })] }))] }));
|
|
106
116
|
}), refs?.map((ref, index) => {
|
|
107
|
-
return (_jsx(OpenAPIRef, { schema: ref,
|
|
117
|
+
return (_jsx(OpenAPIRef, { schema: ref, openapiPath: openapiPath, collectRefs: false }, index));
|
|
108
118
|
})] }));
|
|
109
119
|
};
|
|
110
120
|
export default OpenAPIPath;
|
|
@@ -1,12 +1,18 @@
|
|
|
1
1
|
import { OpenAPIV3_1 } from 'openapi-types';
|
|
2
2
|
export interface OpenAPIRefProps {
|
|
3
|
+
/**
|
|
4
|
+
* The schema name under the OpenAPI schema `definitions` (swagger 2.0) or `components/schemas` (openapi 3.x).
|
|
5
|
+
*/
|
|
3
6
|
schema: string;
|
|
4
|
-
|
|
7
|
+
/**
|
|
8
|
+
* The specific path to the OpenAPI schema, otherwise the first matched will be used.
|
|
9
|
+
*/
|
|
10
|
+
openapiPath?: string;
|
|
5
11
|
collectRefs?: boolean;
|
|
6
12
|
}
|
|
7
13
|
export declare const OpenAPIProperties: ({ properties, openapi, }: {
|
|
8
14
|
properties: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SchemaObject>;
|
|
9
15
|
openapi: OpenAPIV3_1.Document;
|
|
10
16
|
}) => import("react/jsx-runtime").JSX.Element;
|
|
11
|
-
export declare const OpenAPIRef: ({ schema,
|
|
17
|
+
export declare const OpenAPIRef: ({ schema, openapiPath: openapiPath_, collectRefs, }: OpenAPIRefProps) => import("react/jsx-runtime").JSX.Element | null;
|
|
12
18
|
export default OpenAPIRef;
|
|
@@ -4,8 +4,8 @@ import { getCustomMDXComponent } from '@rspress/theme-default';
|
|
|
4
4
|
import { useMemo } from 'react';
|
|
5
5
|
import { DEFAULT_COMMON_REFS, modelName, omitRoutePathRefs, resolveRef, } from '../utils.js';
|
|
6
6
|
import { HeadingTitle } from './_HeadingTitle.js';
|
|
7
|
-
import { RefLink } from './_RefLink.js';
|
|
8
7
|
import { Markdown } from './_Markdown.js';
|
|
8
|
+
import { RefLink } from './_RefLink.js';
|
|
9
9
|
const X = getCustomMDXComponent();
|
|
10
10
|
export const OpenAPIProperties = ({ properties, openapi, }) => {
|
|
11
11
|
return (_jsx(X.ul, { children: Object.entries(properties).map(([name, prop], index) => {
|
|
@@ -65,20 +65,16 @@ const getRefsForSchema = (openapi, schema, knownRefs) => {
|
|
|
65
65
|
collectRefs(refSchema);
|
|
66
66
|
return Array.from(refs);
|
|
67
67
|
};
|
|
68
|
-
export const OpenAPIRef = ({ schema,
|
|
68
|
+
export const OpenAPIRef = ({ schema, openapiPath: openapiPath_, collectRefs = true, }) => {
|
|
69
69
|
const { page } = usePageData();
|
|
70
|
-
const [schemaItem, openapi] = useMemo(() => {
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
openapi_,
|
|
76
|
-
];
|
|
77
|
-
}
|
|
78
|
-
for (const openapi of Object.values(page.openapisMap || {})) {
|
|
70
|
+
const [schemaItem, openapi, openapiPath] = useMemo(() => {
|
|
71
|
+
for (const [pathname, openapi] of Object.entries(page.openapisMap || {})) {
|
|
72
|
+
if (openapiPath_ && pathname !== openapiPath_) {
|
|
73
|
+
continue;
|
|
74
|
+
}
|
|
79
75
|
const schemaItem = openapi.components?.schemas?.[schema];
|
|
80
76
|
if (schemaItem) {
|
|
81
|
-
return [schemaItem, openapi];
|
|
77
|
+
return [schemaItem, openapi, pathname];
|
|
82
78
|
}
|
|
83
79
|
}
|
|
84
80
|
return [];
|
|
@@ -95,6 +91,6 @@ export const OpenAPIRef = ({ schema, openapi: openapi_, collectRefs = true, }) =
|
|
|
95
91
|
}, page.routePath));
|
|
96
92
|
}
|
|
97
93
|
}, [collectRefs, openapi, page.routePath, schema]);
|
|
98
|
-
return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slug: schema, level: 2, children: modelName(schema) }), _jsx(Markdown, { children: schemaItem.description }), schemaItem.properties && (_jsx(OpenAPIProperties, { properties: schemaItem.properties, openapi: openapi })), refs?.map((schema, index) => (_jsx(OpenAPIRef, { schema: schema,
|
|
94
|
+
return (_jsxs(_Fragment, { children: [_jsx(HeadingTitle, { slug: schema, level: 2, children: modelName(schema) }), _jsx(Markdown, { children: schemaItem.description }), schemaItem.properties && (_jsx(OpenAPIProperties, { properties: schemaItem.properties, openapi: openapi })), refs?.map((schema, index) => (_jsx(OpenAPIRef, { schema: schema, openapiPath: openapiPath, collectRefs: false }, index)))] }));
|
|
99
95
|
};
|
|
100
96
|
export default OpenAPIRef;
|
|
@@ -18,7 +18,7 @@ export function Overview(props) {
|
|
|
18
18
|
if ('link' in traverseItem && traverseItem.link) {
|
|
19
19
|
return traverseItem.link;
|
|
20
20
|
}
|
|
21
|
-
if ('items' in traverseItem) {
|
|
21
|
+
if ('items' in traverseItem && traverseItem.items.length) {
|
|
22
22
|
return getChildLink(traverseItem.items[0]);
|
|
23
23
|
}
|
|
24
24
|
return '';
|
package/lib/runtime/types.d.ts
CHANGED
|
@@ -5,6 +5,7 @@ export interface ExtendedPage {
|
|
|
5
5
|
crdsMap?: Record<string, CustomResourceDefinition>;
|
|
6
6
|
openapisMap?: Record<string, OpenAPIV3_1.Document>;
|
|
7
7
|
references?: Record<string, string>;
|
|
8
|
+
pathPrefix?: string;
|
|
8
9
|
}
|
|
9
10
|
export interface ExtendedPageData extends PageData {
|
|
10
11
|
page: PageData['page'] & ExtendedPage;
|
package/lib/utils/types.d.ts
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alauda/doom",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Doctor Doom making docs.",
|
|
6
6
|
"repository": {
|
|
@@ -28,6 +28,7 @@
|
|
|
28
28
|
"clean": "tsc -b src --clean",
|
|
29
29
|
"dev": "yarn swc-node --watch-path src/cli --watch-path src/plugins src/cli/index.ts",
|
|
30
30
|
"doom": "yarn swc-node src/cli/index.ts",
|
|
31
|
+
"fixture": "yarn doom fixture-docs",
|
|
31
32
|
"lint": "run-p 'lint:*'",
|
|
32
33
|
"lint:es": "eslint .",
|
|
33
34
|
"lint:tsc": "tsc -b --noEmit",
|