@kubb/plugin-redoc 5.0.0-beta.42 → 5.0.0-beta.56
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/dist/index.cjs +42 -36
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +39 -30
- package/dist/index.js.map +1 -1
- package/package.json +5 -15
- package/src/plugin.ts +3 -2
- package/src/redoc.tsx +43 -13
- package/extension.yaml +0 -102
- package/static/redoc.hbs +0 -21
package/dist/index.cjs
CHANGED
|
@@ -25,45 +25,49 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
|
|
|
25
25
|
}) : target, mod));
|
|
26
26
|
//#endregion
|
|
27
27
|
let node_path = require("node:path");
|
|
28
|
-
|
|
29
|
-
node_path = __toESM(node_path);
|
|
28
|
+
node_path = __toESM(node_path, 1);
|
|
30
29
|
let _kubb_adapter_oas = require("@kubb/adapter-oas");
|
|
31
30
|
let _kubb_core = require("@kubb/core");
|
|
32
|
-
let node_fs = require("node:fs");
|
|
33
|
-
node_fs = __toESM(node_fs);
|
|
34
|
-
let handlebars = require("handlebars");
|
|
35
|
-
handlebars = __toESM(handlebars);
|
|
36
|
-
//#region ../../internals/utils/src/string.ts
|
|
37
|
-
/**
|
|
38
|
-
* Strips the file extension from a path or file name.
|
|
39
|
-
* Only removes the last `.ext` segment when the dot is not part of a directory name.
|
|
40
|
-
*
|
|
41
|
-
* @example
|
|
42
|
-
* trimExtName('petStore.ts') // 'petStore'
|
|
43
|
-
* trimExtName('/src/models/pet.ts') // '/src/models/pet'
|
|
44
|
-
* trimExtName('/project.v2/gen/pet.ts') // '/project.v2/gen/pet'
|
|
45
|
-
* trimExtName('noExtension') // 'noExtension'
|
|
46
|
-
*/
|
|
47
|
-
function trimExtName(text) {
|
|
48
|
-
const dotIndex = text.lastIndexOf(".");
|
|
49
|
-
if (dotIndex > 0 && !text.includes("/", dotIndex)) return text.slice(0, dotIndex);
|
|
50
|
-
return text;
|
|
51
|
-
}
|
|
52
|
-
//#endregion
|
|
53
31
|
//#region package.json
|
|
54
|
-
var version = "5.0.0-beta.
|
|
32
|
+
var version = "5.0.0-beta.56";
|
|
55
33
|
//#endregion
|
|
56
34
|
//#region src/redoc.tsx
|
|
35
|
+
const htmlEscapes = {
|
|
36
|
+
"&": "&",
|
|
37
|
+
"<": "<",
|
|
38
|
+
">": ">",
|
|
39
|
+
"\"": """,
|
|
40
|
+
"'": "'",
|
|
41
|
+
"`": "`",
|
|
42
|
+
"=": "="
|
|
43
|
+
};
|
|
44
|
+
function escapeHtml(value) {
|
|
45
|
+
return value.replace(/[&<>"'`=]/g, (char) => htmlEscapes[char] ?? char);
|
|
46
|
+
}
|
|
57
47
|
/**
|
|
58
48
|
* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
|
|
59
49
|
* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
|
|
60
50
|
* the generated file works without further build steps.
|
|
61
51
|
*/
|
|
62
|
-
async function getPageHTML(api, { title, disableGoogleFont
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
52
|
+
async function getPageHTML(api, { title, disableGoogleFont } = {}) {
|
|
53
|
+
return `<html>
|
|
54
|
+
|
|
55
|
+
<head>
|
|
56
|
+
<meta charset='utf8' />
|
|
57
|
+
<title>${escapeHtml(title || api.info.title || "ReDoc documentation")}</title>
|
|
58
|
+
<!-- needed for adaptive design -->
|
|
59
|
+
<meta name='viewport' content='width=device-width, initial-scale=1' />
|
|
60
|
+
<style>
|
|
61
|
+
body {
|
|
62
|
+
padding: 0;
|
|
63
|
+
margin: 0;
|
|
64
|
+
}
|
|
65
|
+
</style>
|
|
66
|
+
${disableGoogleFont ? "" : `<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />`}
|
|
67
|
+
</head>
|
|
68
|
+
|
|
69
|
+
<body>
|
|
70
|
+
${`
|
|
67
71
|
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> <\/script>
|
|
68
72
|
<div id="redoc-container"></div>
|
|
69
73
|
<script>
|
|
@@ -72,10 +76,10 @@ async function getPageHTML(api, { title, disableGoogleFont, templateOptions } =
|
|
|
72
76
|
"expandResponses": "200,400"
|
|
73
77
|
}, document.getElementById('redoc-container'))
|
|
74
78
|
<\/script>
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
+
`}
|
|
80
|
+
</body>
|
|
81
|
+
|
|
82
|
+
</html>`;
|
|
79
83
|
}
|
|
80
84
|
//#endregion
|
|
81
85
|
//#region src/plugin.ts
|
|
@@ -105,6 +109,8 @@ const pluginRedocName = "plugin-redoc";
|
|
|
105
109
|
*/
|
|
106
110
|
const pluginRedoc = (0, _kubb_core.definePlugin)((options) => {
|
|
107
111
|
const { output = { path: "docs.html" } } = options;
|
|
112
|
+
const extname = node_path.default.extname(output.path);
|
|
113
|
+
const name = extname ? output.path.slice(0, -extname.length) : output.path;
|
|
108
114
|
return {
|
|
109
115
|
name: pluginRedocName,
|
|
110
116
|
version,
|
|
@@ -112,7 +118,7 @@ const pluginRedoc = (0, _kubb_core.definePlugin)((options) => {
|
|
|
112
118
|
hooks: { async "kubb:plugin:setup"(ctx) {
|
|
113
119
|
ctx.setOptions({
|
|
114
120
|
output,
|
|
115
|
-
name
|
|
121
|
+
name,
|
|
116
122
|
exclude: [],
|
|
117
123
|
override: []
|
|
118
124
|
});
|
|
@@ -120,11 +126,11 @@ const pluginRedoc = (0, _kubb_core.definePlugin)((options) => {
|
|
|
120
126
|
if (adapter?.name !== _kubb_adapter_oas.adapterOasName) throw new Error(`[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \`adapter: adapterOas()\`) in your Kubb config.`);
|
|
121
127
|
const document = adapter.document;
|
|
122
128
|
if (!document) throw new Error(`[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`);
|
|
123
|
-
const root = node_path
|
|
129
|
+
const root = node_path.default.resolve(ctx.config.root, ctx.config.output.path);
|
|
124
130
|
const pageHTML = await getPageHTML(document);
|
|
125
131
|
ctx.injectFile({
|
|
126
132
|
baseName: "docs.html",
|
|
127
|
-
path: node_path
|
|
133
|
+
path: node_path.default.resolve(root, output.path || "./docs.html"),
|
|
128
134
|
sources: [_kubb_core.ast.createSource({
|
|
129
135
|
name: "docs.html",
|
|
130
136
|
nodes: [_kubb_core.ast.createText(pageHTML)]
|
package/dist/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.cjs","names":["path","
|
|
1
|
+
{"version":3,"file":"index.cjs","names":["path","adapterOasName","ast"],"sources":["../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["","import type { AdapterOas } from '@kubb/adapter-oas'\n\ntype BuildDocsOptions = {\n title?: string\n disableGoogleFont?: boolean\n templateOptions?: any\n}\n\nconst htmlEscapes: Record<string, string> = {\n '&': '&',\n '<': '<',\n '>': '>',\n '\"': '"',\n \"'\": ''',\n '`': '`',\n '=': '=',\n}\n\nfunction escapeHtml(value: string) {\n return value.replace(/[&<>\"'`=]/g, (char) => htmlEscapes[char] ?? char)\n}\n\n/**\n * Renders a self-contained Redoc HTML page for an OpenAPI document. The page\n * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so\n * the generated file works without further build steps.\n */\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont }: BuildDocsOptions = {}) {\n const pageTitle = escapeHtml(title || api.info.title || 'ReDoc documentation')\n const googleFont = disableGoogleFont\n ? ''\n : `<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />`\n const redocHTML = `\n <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n const data = ${JSON.stringify(api, null, 2)};\n Redoc.init(data, {\n \"expandResponses\": \"200,400\"\n }, document.getElementById('redoc-container'))\n </script>\n `\n\n return `<html>\n\n <head>\n <meta charset='utf8' />\n <title>${pageTitle}</title>\n <!-- needed for adaptive design -->\n <meta name='viewport' content='width=device-width, initial-scale=1' />\n <style>\n body {\n padding: 0;\n margin: 0;\n }\n </style>\n ${googleFont}\n </head>\n\n <body>\n ${redocHTML}\n </body>\n\n</html>`\n}\n","import path from 'node:path'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and\n * cross-plugin dependency references.\n */\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\n/**\n * Generates a self-contained static HTML documentation page from your OpenAPI\n * spec using Redoc. The file is regenerated on every Kubb build, so the docs\n * stay in lockstep with the spec the rest of your code is generated from.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { pluginRedoc } from '@kubb/plugin-redoc'\n *\n * export default defineConfig({\n * input: { path: './petStore.yaml' },\n * output: { path: './src/gen' },\n * plugins: [\n * pluginRedoc({ output: { path: 'docs.html' } }),\n * ],\n * })\n * ```\n */\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n const { output = { path: 'docs.html' } } = options\n const extname = path.extname(output.path)\n const name = extname ? output.path.slice(0, -extname.length) : output.path\n\n return {\n name: pluginRedocName,\n version,\n options,\n hooks: {\n async 'kubb:plugin:setup'(ctx) {\n ctx.setOptions({\n output,\n name,\n exclude: [],\n override: [],\n })\n\n const adapter = ctx.config.adapter\n\n if (adapter?.name !== adapterOasName) {\n throw new Error(\n `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n )\n }\n\n const document = (adapter as Adapter<AdapterOas>).document\n\n if (!document) {\n throw new Error(\n `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n )\n }\n\n const root = path.resolve(ctx.config.root, ctx.config.output.path)\n const pageHTML = await getPageHTML(document)\n\n ctx.injectFile({\n baseName: 'docs.html',\n path: path.resolve(root, output.path || './docs.html'),\n sources: [\n ast.createSource({\n name: 'docs.html',\n nodes: [ast.createText(pageHTML)],\n }),\n ],\n })\n },\n },\n }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACQA,MAAM,cAAsC;CAC1C,KAAK;CACL,KAAK;CACL,KAAK;CACL,MAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;AACP;AAEA,SAAS,WAAW,OAAe;CACjC,OAAO,MAAM,QAAQ,eAAe,SAAS,YAAY,SAAS,IAAI;AACxE;;;;;;AAOA,eAAsB,YAAY,KAA6B,EAAE,OAAO,sBAAwC,CAAC,GAAG;CAgBlH,OAAO;;;;aAfW,WAAW,SAAS,IAAI,KAAK,SAAS,qBAmBrC,EAAE;;;;;;;;;MAlBF,oBACf,KACA,qHAyBW;;;;MAIX;;;;kBAxBY,KAAK,UAAU,KAAK,MAAM,CAAC,EAAE;;;;;MAwB/B;;;;AAIhB;;;;;;;ACnDA,MAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqB/B,MAAa,eAAA,GAAA,WAAA,aAAA,EAAyC,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,MAAM;CAC3C,MAAM,UAAUA,UAAAA,QAAK,QAAQ,OAAO,IAAI;CACxC,MAAM,OAAO,UAAU,OAAO,KAAK,MAAM,GAAG,CAAC,QAAQ,MAAM,IAAI,OAAO;CAEtE,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA;IACA,SAAS,CAAC;IACV,UAAU,CAAC;GACb,CAAC;GAED,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAASC,kBAAAA,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,sIACtB;GAGF,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,wHACtB;GAGF,MAAM,OAAOD,UAAAA,QAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,IAAI;GACjE,MAAM,WAAW,MAAM,YAAY,QAAQ;GAE3C,IAAI,WAAW;IACb,UAAU;IACV,MAAMA,UAAAA,QAAK,QAAQ,MAAM,OAAO,QAAQ,aAAa;IACrD,SAAS,CACPE,WAAAA,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAACA,WAAAA,IAAI,WAAW,QAAQ,CAAC;IAClC,CAAC,CACH;GACF,CAAC;EACH,EACF;CACF;AACF,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -2,39 +2,46 @@ import "./chunk-C0LytTxp.js";
|
|
|
2
2
|
import path from "node:path";
|
|
3
3
|
import { adapterOasName } from "@kubb/adapter-oas";
|
|
4
4
|
import { ast, definePlugin } from "@kubb/core";
|
|
5
|
-
import fs from "node:fs";
|
|
6
|
-
import pkg from "handlebars";
|
|
7
|
-
//#region ../../internals/utils/src/string.ts
|
|
8
|
-
/**
|
|
9
|
-
* Strips the file extension from a path or file name.
|
|
10
|
-
* Only removes the last `.ext` segment when the dot is not part of a directory name.
|
|
11
|
-
*
|
|
12
|
-
* @example
|
|
13
|
-
* trimExtName('petStore.ts') // 'petStore'
|
|
14
|
-
* trimExtName('/src/models/pet.ts') // '/src/models/pet'
|
|
15
|
-
* trimExtName('/project.v2/gen/pet.ts') // '/project.v2/gen/pet'
|
|
16
|
-
* trimExtName('noExtension') // 'noExtension'
|
|
17
|
-
*/
|
|
18
|
-
function trimExtName(text) {
|
|
19
|
-
const dotIndex = text.lastIndexOf(".");
|
|
20
|
-
if (dotIndex > 0 && !text.includes("/", dotIndex)) return text.slice(0, dotIndex);
|
|
21
|
-
return text;
|
|
22
|
-
}
|
|
23
|
-
//#endregion
|
|
24
5
|
//#region package.json
|
|
25
|
-
var version = "5.0.0-beta.
|
|
6
|
+
var version = "5.0.0-beta.56";
|
|
26
7
|
//#endregion
|
|
27
8
|
//#region src/redoc.tsx
|
|
9
|
+
const htmlEscapes = {
|
|
10
|
+
"&": "&",
|
|
11
|
+
"<": "<",
|
|
12
|
+
">": ">",
|
|
13
|
+
"\"": """,
|
|
14
|
+
"'": "'",
|
|
15
|
+
"`": "`",
|
|
16
|
+
"=": "="
|
|
17
|
+
};
|
|
18
|
+
function escapeHtml(value) {
|
|
19
|
+
return value.replace(/[&<>"'`=]/g, (char) => htmlEscapes[char] ?? char);
|
|
20
|
+
}
|
|
28
21
|
/**
|
|
29
22
|
* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
|
|
30
23
|
* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
|
|
31
24
|
* the generated file works without further build steps.
|
|
32
25
|
*/
|
|
33
|
-
async function getPageHTML(api, { title, disableGoogleFont
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
26
|
+
async function getPageHTML(api, { title, disableGoogleFont } = {}) {
|
|
27
|
+
return `<html>
|
|
28
|
+
|
|
29
|
+
<head>
|
|
30
|
+
<meta charset='utf8' />
|
|
31
|
+
<title>${escapeHtml(title || api.info.title || "ReDoc documentation")}</title>
|
|
32
|
+
<!-- needed for adaptive design -->
|
|
33
|
+
<meta name='viewport' content='width=device-width, initial-scale=1' />
|
|
34
|
+
<style>
|
|
35
|
+
body {
|
|
36
|
+
padding: 0;
|
|
37
|
+
margin: 0;
|
|
38
|
+
}
|
|
39
|
+
</style>
|
|
40
|
+
${disableGoogleFont ? "" : `<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />`}
|
|
41
|
+
</head>
|
|
42
|
+
|
|
43
|
+
<body>
|
|
44
|
+
${`
|
|
38
45
|
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> <\/script>
|
|
39
46
|
<div id="redoc-container"></div>
|
|
40
47
|
<script>
|
|
@@ -43,10 +50,10 @@ async function getPageHTML(api, { title, disableGoogleFont, templateOptions } =
|
|
|
43
50
|
"expandResponses": "200,400"
|
|
44
51
|
}, document.getElementById('redoc-container'))
|
|
45
52
|
<\/script>
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
53
|
+
`}
|
|
54
|
+
</body>
|
|
55
|
+
|
|
56
|
+
</html>`;
|
|
50
57
|
}
|
|
51
58
|
//#endregion
|
|
52
59
|
//#region src/plugin.ts
|
|
@@ -76,6 +83,8 @@ const pluginRedocName = "plugin-redoc";
|
|
|
76
83
|
*/
|
|
77
84
|
const pluginRedoc = definePlugin((options) => {
|
|
78
85
|
const { output = { path: "docs.html" } } = options;
|
|
86
|
+
const extname = path.extname(output.path);
|
|
87
|
+
const name = extname ? output.path.slice(0, -extname.length) : output.path;
|
|
79
88
|
return {
|
|
80
89
|
name: pluginRedocName,
|
|
81
90
|
version,
|
|
@@ -83,7 +92,7 @@ const pluginRedoc = definePlugin((options) => {
|
|
|
83
92
|
hooks: { async "kubb:plugin:setup"(ctx) {
|
|
84
93
|
ctx.setOptions({
|
|
85
94
|
output,
|
|
86
|
-
name
|
|
95
|
+
name,
|
|
87
96
|
exclude: [],
|
|
88
97
|
override: []
|
|
89
98
|
});
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","names":[],"sources":["
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../package.json","../src/redoc.tsx","../src/plugin.ts"],"sourcesContent":["","import type { AdapterOas } from '@kubb/adapter-oas'\n\ntype BuildDocsOptions = {\n title?: string\n disableGoogleFont?: boolean\n templateOptions?: any\n}\n\nconst htmlEscapes: Record<string, string> = {\n '&': '&',\n '<': '<',\n '>': '>',\n '\"': '"',\n \"'\": ''',\n '`': '`',\n '=': '=',\n}\n\nfunction escapeHtml(value: string) {\n return value.replace(/[&<>\"'`=]/g, (char) => htmlEscapes[char] ?? char)\n}\n\n/**\n * Renders a self-contained Redoc HTML page for an OpenAPI document. The page\n * embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so\n * the generated file works without further build steps.\n */\nexport async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont }: BuildDocsOptions = {}) {\n const pageTitle = escapeHtml(title || api.info.title || 'ReDoc documentation')\n const googleFont = disableGoogleFont\n ? ''\n : `<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />`\n const redocHTML = `\n <script src=\"https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\"> </script>\n <div id=\"redoc-container\"></div>\n <script>\n const data = ${JSON.stringify(api, null, 2)};\n Redoc.init(data, {\n \"expandResponses\": \"200,400\"\n }, document.getElementById('redoc-container'))\n </script>\n `\n\n return `<html>\n\n <head>\n <meta charset='utf8' />\n <title>${pageTitle}</title>\n <!-- needed for adaptive design -->\n <meta name='viewport' content='width=device-width, initial-scale=1' />\n <style>\n body {\n padding: 0;\n margin: 0;\n }\n </style>\n ${googleFont}\n </head>\n\n <body>\n ${redocHTML}\n </body>\n\n</html>`\n}\n","import path from 'node:path'\nimport type { AdapterOas } from '@kubb/adapter-oas'\nimport { adapterOasName } from '@kubb/adapter-oas'\n\nimport { type Adapter, ast, definePlugin } from '@kubb/core'\nimport { version } from '../package.json'\nimport { getPageHTML } from './redoc.tsx'\nimport type { PluginRedoc } from './types.ts'\n\n/**\n * Canonical plugin name for `@kubb/plugin-redoc`. Used for driver lookups and\n * cross-plugin dependency references.\n */\nexport const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']\n\n/**\n * Generates a self-contained static HTML documentation page from your OpenAPI\n * spec using Redoc. The file is regenerated on every Kubb build, so the docs\n * stay in lockstep with the spec the rest of your code is generated from.\n *\n * @example\n * ```ts\n * import { defineConfig } from 'kubb'\n * import { pluginRedoc } from '@kubb/plugin-redoc'\n *\n * export default defineConfig({\n * input: { path: './petStore.yaml' },\n * output: { path: './src/gen' },\n * plugins: [\n * pluginRedoc({ output: { path: 'docs.html' } }),\n * ],\n * })\n * ```\n */\nexport const pluginRedoc = definePlugin<PluginRedoc>((options) => {\n const { output = { path: 'docs.html' } } = options\n const extname = path.extname(output.path)\n const name = extname ? output.path.slice(0, -extname.length) : output.path\n\n return {\n name: pluginRedocName,\n version,\n options,\n hooks: {\n async 'kubb:plugin:setup'(ctx) {\n ctx.setOptions({\n output,\n name,\n exclude: [],\n override: [],\n })\n\n const adapter = ctx.config.adapter\n\n if (adapter?.name !== adapterOasName) {\n throw new Error(\n `[${pluginRedocName}] plugin-redoc requires the OpenAPI adapter. Make sure you are using adapterOas (e.g. \\`adapter: adapterOas()\\`) in your Kubb config.`,\n )\n }\n\n const document = (adapter as Adapter<AdapterOas>).document\n\n if (!document) {\n throw new Error(\n `[${pluginRedocName}] No OpenAPI document found. The adapterOas did not produce a document — ensure the adapter has run before this plugin.`,\n )\n }\n\n const root = path.resolve(ctx.config.root, ctx.config.output.path)\n const pageHTML = await getPageHTML(document)\n\n ctx.injectFile({\n baseName: 'docs.html',\n path: path.resolve(root, output.path || './docs.html'),\n sources: [\n ast.createSource({\n name: 'docs.html',\n nodes: [ast.createText(pageHTML)],\n }),\n ],\n })\n },\n },\n }\n})\n\nexport default pluginRedoc\n"],"mappings":";;;;;;;;ACQA,MAAM,cAAsC;CAC1C,KAAK;CACL,KAAK;CACL,KAAK;CACL,MAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;AACP;AAEA,SAAS,WAAW,OAAe;CACjC,OAAO,MAAM,QAAQ,eAAe,SAAS,YAAY,SAAS,IAAI;AACxE;;;;;;AAOA,eAAsB,YAAY,KAA6B,EAAE,OAAO,sBAAwC,CAAC,GAAG;CAgBlH,OAAO;;;;aAfW,WAAW,SAAS,IAAI,KAAK,SAAS,qBAmBrC,EAAE;;;;;;;;;MAlBF,oBACf,KACA,qHAyBW;;;;MAIX;;;;kBAxBY,KAAK,UAAU,KAAK,MAAM,CAAC,EAAE;;;;;MAwB/B;;;;AAIhB;;;;;;;ACnDA,MAAa,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqB/B,MAAa,cAAc,cAA2B,YAAY;CAChE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,MAAM;CAC3C,MAAM,UAAU,KAAK,QAAQ,OAAO,IAAI;CACxC,MAAM,OAAO,UAAU,OAAO,KAAK,MAAM,GAAG,CAAC,QAAQ,MAAM,IAAI,OAAO;CAEtE,OAAO;EACL,MAAM;EACN;EACA;EACA,OAAO,EACL,MAAM,oBAAoB,KAAK;GAC7B,IAAI,WAAW;IACb;IACA;IACA,SAAS,CAAC;IACV,UAAU,CAAC;GACb,CAAC;GAED,MAAM,UAAU,IAAI,OAAO;GAE3B,IAAI,SAAS,SAAS,gBACpB,MAAM,IAAI,MACR,IAAI,gBAAgB,sIACtB;GAGF,MAAM,WAAY,QAAgC;GAElD,IAAI,CAAC,UACH,MAAM,IAAI,MACR,IAAI,gBAAgB,wHACtB;GAGF,MAAM,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,IAAI,OAAO,OAAO,IAAI;GACjE,MAAM,WAAW,MAAM,YAAY,QAAQ;GAE3C,IAAI,WAAW;IACb,UAAU;IACV,MAAM,KAAK,QAAQ,MAAM,OAAO,QAAQ,aAAa;IACrD,SAAS,CACP,IAAI,aAAa;KACf,MAAM;KACN,OAAO,CAAC,IAAI,WAAW,QAAQ,CAAC;IAClC,CAAC,CACH;GACF,CAAC;EACH,EACF;CACF;AACF,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubb/plugin-redoc",
|
|
3
|
-
"version": "5.0.0-beta.
|
|
3
|
+
"version": "5.0.0-beta.56",
|
|
4
4
|
"description": "Generate a beautiful, interactive ReDoc API reference page from your OpenAPI specification. Produces a standalone HTML file with a responsive, developer-friendly UI.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"api-docs",
|
|
@@ -24,8 +24,6 @@
|
|
|
24
24
|
"files": [
|
|
25
25
|
"src",
|
|
26
26
|
"dist",
|
|
27
|
-
"static",
|
|
28
|
-
"extension.yaml",
|
|
29
27
|
"!/**/**.test.**",
|
|
30
28
|
"!/**/__tests__/**",
|
|
31
29
|
"!/**/__snapshots__/**"
|
|
@@ -50,26 +48,18 @@
|
|
|
50
48
|
"registry": "https://registry.npmjs.org/"
|
|
51
49
|
},
|
|
52
50
|
"dependencies": {
|
|
53
|
-
"@kubb/adapter-oas": "5.0.0-beta.
|
|
54
|
-
"@kubb/core": "5.0.0-beta.
|
|
55
|
-
"handlebars": "^4.7.9"
|
|
51
|
+
"@kubb/adapter-oas": "5.0.0-beta.55",
|
|
52
|
+
"@kubb/core": "5.0.0-beta.55"
|
|
56
53
|
},
|
|
57
54
|
"devDependencies": {
|
|
58
55
|
"@internals/utils": "0.0.0"
|
|
59
56
|
},
|
|
60
|
-
"size-limit": [
|
|
61
|
-
{
|
|
62
|
-
"path": "./dist/*.js",
|
|
63
|
-
"limit": "510 KiB",
|
|
64
|
-
"gzip": true
|
|
65
|
-
}
|
|
66
|
-
],
|
|
67
57
|
"engines": {
|
|
68
58
|
"node": ">=22"
|
|
69
59
|
},
|
|
70
60
|
"scripts": {
|
|
71
|
-
"build": "tsdown
|
|
72
|
-
"clean": "
|
|
61
|
+
"build": "tsdown",
|
|
62
|
+
"clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
|
|
73
63
|
"lint": "oxlint .",
|
|
74
64
|
"lint:fix": "oxlint --fix .",
|
|
75
65
|
"release": "pnpm publish --no-git-check",
|
package/src/plugin.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import path from 'node:path'
|
|
2
|
-
import { trimExtName } from '@internals/utils'
|
|
3
2
|
import type { AdapterOas } from '@kubb/adapter-oas'
|
|
4
3
|
import { adapterOasName } from '@kubb/adapter-oas'
|
|
5
4
|
|
|
@@ -35,6 +34,8 @@ export const pluginRedocName = 'plugin-redoc' satisfies PluginRedoc['name']
|
|
|
35
34
|
*/
|
|
36
35
|
export const pluginRedoc = definePlugin<PluginRedoc>((options) => {
|
|
37
36
|
const { output = { path: 'docs.html' } } = options
|
|
37
|
+
const extname = path.extname(output.path)
|
|
38
|
+
const name = extname ? output.path.slice(0, -extname.length) : output.path
|
|
38
39
|
|
|
39
40
|
return {
|
|
40
41
|
name: pluginRedocName,
|
|
@@ -44,7 +45,7 @@ export const pluginRedoc = definePlugin<PluginRedoc>((options) => {
|
|
|
44
45
|
async 'kubb:plugin:setup'(ctx) {
|
|
45
46
|
ctx.setOptions({
|
|
46
47
|
output,
|
|
47
|
-
name
|
|
48
|
+
name,
|
|
48
49
|
exclude: [],
|
|
49
50
|
override: [],
|
|
50
51
|
})
|
package/src/redoc.tsx
CHANGED
|
@@ -1,7 +1,4 @@
|
|
|
1
|
-
import fs from 'node:fs'
|
|
2
|
-
import path from 'node:path'
|
|
3
1
|
import type { AdapterOas } from '@kubb/adapter-oas'
|
|
4
|
-
import pkg from 'handlebars'
|
|
5
2
|
|
|
6
3
|
type BuildDocsOptions = {
|
|
7
4
|
title?: string
|
|
@@ -9,17 +6,31 @@ type BuildDocsOptions = {
|
|
|
9
6
|
templateOptions?: any
|
|
10
7
|
}
|
|
11
8
|
|
|
9
|
+
const htmlEscapes: Record<string, string> = {
|
|
10
|
+
'&': '&',
|
|
11
|
+
'<': '<',
|
|
12
|
+
'>': '>',
|
|
13
|
+
'"': '"',
|
|
14
|
+
"'": ''',
|
|
15
|
+
'`': '`',
|
|
16
|
+
'=': '=',
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function escapeHtml(value: string) {
|
|
20
|
+
return value.replace(/[&<>"'`=]/g, (char) => htmlEscapes[char] ?? char)
|
|
21
|
+
}
|
|
22
|
+
|
|
12
23
|
/**
|
|
13
24
|
* Renders a self-contained Redoc HTML page for an OpenAPI document. The page
|
|
14
25
|
* embeds the spec inline and pulls Redoc's bundle from a CDN at runtime, so
|
|
15
26
|
* the generated file works without further build steps.
|
|
16
27
|
*/
|
|
17
|
-
export async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont
|
|
18
|
-
const
|
|
19
|
-
const
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
28
|
+
export async function getPageHTML(api: AdapterOas['document'], { title, disableGoogleFont }: BuildDocsOptions = {}) {
|
|
29
|
+
const pageTitle = escapeHtml(title || api.info.title || 'ReDoc documentation')
|
|
30
|
+
const googleFont = disableGoogleFont
|
|
31
|
+
? ''
|
|
32
|
+
: `<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />`
|
|
33
|
+
const redocHTML = `
|
|
23
34
|
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
|
|
24
35
|
<div id="redoc-container"></div>
|
|
25
36
|
<script>
|
|
@@ -28,8 +39,27 @@ export async function getPageHTML(api: AdapterOas['document'], { title, disableG
|
|
|
28
39
|
"expandResponses": "200,400"
|
|
29
40
|
}, document.getElementById('redoc-container'))
|
|
30
41
|
</script>
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
42
|
+
`
|
|
43
|
+
|
|
44
|
+
return `<html>
|
|
45
|
+
|
|
46
|
+
<head>
|
|
47
|
+
<meta charset='utf8' />
|
|
48
|
+
<title>${pageTitle}</title>
|
|
49
|
+
<!-- needed for adaptive design -->
|
|
50
|
+
<meta name='viewport' content='width=device-width, initial-scale=1' />
|
|
51
|
+
<style>
|
|
52
|
+
body {
|
|
53
|
+
padding: 0;
|
|
54
|
+
margin: 0;
|
|
55
|
+
}
|
|
56
|
+
</style>
|
|
57
|
+
${googleFont}
|
|
58
|
+
</head>
|
|
59
|
+
|
|
60
|
+
<body>
|
|
61
|
+
${redocHTML}
|
|
62
|
+
</body>
|
|
63
|
+
|
|
64
|
+
</html>`
|
|
35
65
|
}
|
package/extension.yaml
DELETED
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
$schema: https://kubb.dev/schemas/extension.json
|
|
2
|
-
kind: plugin
|
|
3
|
-
id: plugin-redoc
|
|
4
|
-
name: Redoc
|
|
5
|
-
description: Render your OpenAPI spec as a single-file HTML page using Redoc, regenerated as part of the Kubb build.
|
|
6
|
-
category: documentation
|
|
7
|
-
type: official
|
|
8
|
-
npmPackage: '@kubb/plugin-redoc'
|
|
9
|
-
docsPath: /plugins/plugin-redoc
|
|
10
|
-
repo: https://github.com/kubb-labs/plugins
|
|
11
|
-
maintainers:
|
|
12
|
-
- name: Stijn Van Hulle
|
|
13
|
-
github: stijnvanhulle
|
|
14
|
-
compatibility:
|
|
15
|
-
kubb: '>=5.0.0'
|
|
16
|
-
node: '>=22'
|
|
17
|
-
tags:
|
|
18
|
-
- redoc
|
|
19
|
-
- api-docs
|
|
20
|
-
- documentation
|
|
21
|
-
- interactive-docs
|
|
22
|
-
- codegen
|
|
23
|
-
- openapi
|
|
24
|
-
dependencies: []
|
|
25
|
-
resources:
|
|
26
|
-
documentation: https://kubb.dev/plugins/plugin-redoc
|
|
27
|
-
repository: https://github.com/kubb-labs/plugins
|
|
28
|
-
issues: https://github.com/kubb-labs/plugins/issues
|
|
29
|
-
changelog: https://github.com/kubb-labs/plugins/blob/main/packages/plugin-redoc/CHANGELOG.md
|
|
30
|
-
codesandbox: https://codesandbox.io/p/github/kubb-labs/plugins/main/examples/simple-single
|
|
31
|
-
featured: false
|
|
32
|
-
icon:
|
|
33
|
-
light: https://kubb.dev/feature/openapi.svg
|
|
34
|
-
intro: |
|
|
35
|
-
# @kubb/plugin-redoc
|
|
36
|
-
|
|
37
|
-
Generate a static HTML documentation page for your OpenAPI spec using [Redoc](https://redocly.com/). The page is self-contained — drop it on any static host or open it locally.
|
|
38
|
-
|
|
39
|
-
Because the file is regenerated on every Kubb build, your docs stay in lockstep with the spec your code was generated from.
|
|
40
|
-
options:
|
|
41
|
-
- name: output
|
|
42
|
-
type: '{ path: string }'
|
|
43
|
-
required: false
|
|
44
|
-
default: "{ path: 'docs.html' }"
|
|
45
|
-
description: Output location of the generated HTML file.
|
|
46
|
-
properties:
|
|
47
|
-
- name: path
|
|
48
|
-
type: string
|
|
49
|
-
required: true
|
|
50
|
-
description: |
|
|
51
|
-
File path of the generated HTML, relative to the global `output.path`.
|
|
52
|
-
|
|
53
|
-
Use a `.html` extension. Unlike most plugins, this option points at a single file rather than a directory.
|
|
54
|
-
tip: |
|
|
55
|
-
When `output.path` points to a single file, the `group` option cannot be used because every operation ends up in the same file.
|
|
56
|
-
examples:
|
|
57
|
-
- name: kubb.config.ts
|
|
58
|
-
files:
|
|
59
|
-
- lang: typescript
|
|
60
|
-
twoslash: false
|
|
61
|
-
code: |
|
|
62
|
-
import { defineConfig } from 'kubb'
|
|
63
|
-
import { pluginTs } from '@kubb/plugin-ts'
|
|
64
|
-
|
|
65
|
-
export default defineConfig({
|
|
66
|
-
input: { path: './petStore.yaml' },
|
|
67
|
-
output: { path: './src/gen' },
|
|
68
|
-
plugins: [
|
|
69
|
-
pluginTs({
|
|
70
|
-
output: { path: './types' },
|
|
71
|
-
}),
|
|
72
|
-
],
|
|
73
|
-
})
|
|
74
|
-
- name: Resulting tree
|
|
75
|
-
files:
|
|
76
|
-
- lang: text
|
|
77
|
-
twoslash: false
|
|
78
|
-
code: |
|
|
79
|
-
src/
|
|
80
|
-
└── gen/
|
|
81
|
-
└── types/
|
|
82
|
-
├── Pet.ts
|
|
83
|
-
└── Store.ts
|
|
84
|
-
default: "'docs.html'"
|
|
85
|
-
examples:
|
|
86
|
-
- name: kubb.config.ts
|
|
87
|
-
files:
|
|
88
|
-
- lang: typescript
|
|
89
|
-
twoslash: false
|
|
90
|
-
code: |
|
|
91
|
-
import { defineConfig } from 'kubb'
|
|
92
|
-
import { pluginRedoc } from '@kubb/plugin-redoc'
|
|
93
|
-
|
|
94
|
-
export default defineConfig({
|
|
95
|
-
input: { path: './petStore.yaml' },
|
|
96
|
-
output: { path: './src/gen' },
|
|
97
|
-
plugins: [
|
|
98
|
-
pluginRedoc({
|
|
99
|
-
output: { path: 'docs.html' },
|
|
100
|
-
}),
|
|
101
|
-
],
|
|
102
|
-
})
|
package/static/redoc.hbs
DELETED
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
<html>
|
|
2
|
-
|
|
3
|
-
<head>
|
|
4
|
-
<meta charset='utf8' />
|
|
5
|
-
<title>{{title}}</title>
|
|
6
|
-
<!-- needed for adaptive design -->
|
|
7
|
-
<meta name='viewport' content='width=device-width, initial-scale=1' />
|
|
8
|
-
<style>
|
|
9
|
-
body {
|
|
10
|
-
padding: 0;
|
|
11
|
-
margin: 0;
|
|
12
|
-
}
|
|
13
|
-
</style>
|
|
14
|
-
{{#unless disableGoogleFont}}<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />{{/unless}}
|
|
15
|
-
</head>
|
|
16
|
-
|
|
17
|
-
<body>
|
|
18
|
-
{{{redocHTML}}}
|
|
19
|
-
</body>
|
|
20
|
-
|
|
21
|
-
</html>
|