Skip to content

Commit 9732053

Browse files
sserratasserrata
committed
Add option to disable frontmatter api prop compression (#800)
* add option to disable frontmatter openapi snippet compression * disable compression for petstore * explicitly check for true * handle both compressed and uncompression api prop
1 parent f621777 commit 9732053

File tree

5 files changed

+303
-7
lines changed

5 files changed

+303
-7
lines changed

‎demo/docusaurus.config.js

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
// @ts-check
2+
// Note: type annotations allow type checking and IDEs autocompletion
3+
4+
const { DOCUSAURUS_VERSION } = require("@docusaurus/utils");
5+
6+
/** @type {import('@docusaurus/types').Config} */
7+
const config = {
8+
title: "Docusaurus OpenAPI Docs",
9+
tagline: "OpenAPI plugin for generating API reference docs in Docusaurus v2",
10+
url: "https://docusaurus-openapi.tryingpan.dev",
11+
baseUrl: "/",
12+
onBrokenLinks: "warn",
13+
onBrokenMarkdownLinks: "warn",
14+
favicon: "img/favicon.ico",
15+
organizationName: "PaloAltoNetworks",
16+
projectName: "docusaurus-openapi-docs",
17+
18+
presets: [
19+
[
20+
"classic",
21+
/** @type {import('@docusaurus/preset-classic').Options} */
22+
({
23+
docs: {
24+
routeBasePath: "/",
25+
sidebarPath: require.resolve("./sidebars.js"),
26+
editUrl:
27+
"https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/tree/main/demo",
28+
docLayoutComponent: "@theme/DocPage",
29+
docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
30+
},
31+
blog: false,
32+
theme: {
33+
customCss: require.resolve("./src/css/custom.css"),
34+
},
35+
gtag: {
36+
trackingID: "GTM-THVM29S",
37+
anonymizeIP: false,
38+
},
39+
}),
40+
],
41+
],
42+
43+
themeConfig:
44+
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
45+
({
46+
docs: {
47+
sidebar: {
48+
hideable: true,
49+
},
50+
},
51+
navbar: {
52+
title: "OpenAPI Docs",
53+
logo: {
54+
alt: "Keytar",
55+
src: "img/docusaurus-openapi-docs-logo.svg",
56+
},
57+
items: [
58+
{
59+
type: "doc",
60+
docId: "intro",
61+
position: "left",
62+
label: "Docs",
63+
},
64+
{
65+
type: "dropdown",
66+
label: "Demos",
67+
position: "left",
68+
items: [
69+
{
70+
label: "API Zoo",
71+
to: "/category/petstore-api",
72+
},
73+
{
74+
label: "Petstore (versioned)",
75+
to: "/category/petstore-versioned-api",
76+
},
77+
],
78+
},
79+
{
80+
href: "https://medium.com/palo-alto-networks-developer-blog",
81+
position: "right",
82+
className: "header-medium-link",
83+
"aria-label": "Palo Alto Networks Developer Blog",
84+
},
85+
{
86+
href: "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs",
87+
position: "right",
88+
className: "header-github-link",
89+
"aria-label": "GitHub repository",
90+
},
91+
],
92+
},
93+
footer: {
94+
style: "dark",
95+
links: [
96+
{
97+
title: "Docs",
98+
items: [
99+
{
100+
label: "OpenAPI Docs",
101+
to: "/",
102+
},
103+
],
104+
},
105+
{
106+
title: "Community",
107+
items: [
108+
{
109+
label: "Stack Overflow",
110+
href: "https://stackoverflow.com/questions/tagged/docusaurus",
111+
},
112+
{
113+
label: "Discord",
114+
href: "https://discordapp.com/invite/docusaurus",
115+
},
116+
{
117+
label: "Twitter",
118+
href: "https://twitter.com/docusaurus",
119+
},
120+
],
121+
},
122+
{
123+
title: "More",
124+
items: [
125+
{
126+
label: "Blog",
127+
href: "https://medium.com/palo-alto-networks-developer-blog",
128+
},
129+
{
130+
label: "GitHub",
131+
href: "https://github.com/PaloAltoNetworks/docusaurus-openapi-docs",
132+
},
133+
],
134+
},
135+
],
136+
copyright: `Copyright © ${new Date().getFullYear()} Palo Alto Networks, Inc. Built with Docusaurus ${DOCUSAURUS_VERSION}.`,
137+
},
138+
prism: {
139+
additionalLanguages: ["ruby", "csharp", "php", "java", "powershell"],
140+
},
141+
languageTabs: [
142+
{
143+
highlight: "bash",
144+
language: "curl",
145+
logoClass: "bash",
146+
},
147+
{
148+
highlight: "python",
149+
language: "python",
150+
logoClass: "python",
151+
variant: "requests",
152+
},
153+
{
154+
highlight: "go",
155+
language: "go",
156+
logoClass: "go",
157+
},
158+
{
159+
highlight: "javascript",
160+
language: "nodejs",
161+
logoClass: "nodejs",
162+
variant: "axios",
163+
},
164+
{
165+
highlight: "ruby",
166+
language: "ruby",
167+
logoClass: "ruby",
168+
},
169+
{
170+
highlight: "csharp",
171+
language: "csharp",
172+
logoClass: "csharp",
173+
variant: "httpclient",
174+
},
175+
{
176+
highlight: "php",
177+
language: "php",
178+
logoClass: "php",
179+
},
180+
{
181+
highlight: "java",
182+
language: "java",
183+
logoClass: "java",
184+
variant: "unirest",
185+
},
186+
{
187+
highlight: "powershell",
188+
language: "powershell",
189+
logoClass: "powershell",
190+
},
191+
],
192+
algolia: {
193+
apiKey: "441074cace987cbf4640c039ebed303c",
194+
appId: "J0EABTYI1A",
195+
indexName: "docusaurus-openapi",
196+
},
197+
announcementBar: {
198+
id: "announcementBar_1",
199+
content:
200+
"🥳 First v2.0.0 stable release! Currently only compatible with Docusaurus v2.4.1 -> v2.4.3",
201+
},
202+
}),
203+
204+
plugins: [
205+
[
206+
"docusaurus-plugin-openapi-docs",
207+
{
208+
id: "openapi",
209+
docsPluginId: "classic",
210+
config: {
211+
petstore_versioned: {
212+
specPath: "examples/petstore.yaml",
213+
outputDir: "docs/petstore_versioned", // No trailing slash
214+
sidebarOptions: {
215+
groupPathsBy: "tag",
216+
categoryLinkSource: "tag",
217+
},
218+
version: "2.0.0", // Current version
219+
label: "v2.0.0", // Current version label
220+
baseUrl: "/petstore_versioned/swagger-petstore-yaml", // Leading slash is important
221+
versions: {
222+
"1.0.0": {
223+
specPath: "examples/petstore-1.0.0.yaml",
224+
outputDir: "docs/petstore_versioned/1.0.0", // No trailing slash
225+
label: "v1.0.0",
226+
baseUrl: "/petstore_versioned/1.0.0/swagger-petstore-yaml", // Leading slash is important
227+
},
228+
},
229+
},
230+
petstore: {
231+
specPath: "examples/petstore.yaml",
232+
proxy: "https://cors.pan.dev",
233+
outputDir: "docs/petstore",
234+
sidebarOptions: {
235+
groupPathsBy: "tag",
236+
categoryLinkSource: "tag",
237+
},
238+
template: "api.mustache", // Customize API MDX with mustache template
239+
downloadUrl:
240+
"https://raw.githubusercontent.com/PaloAltoNetworks/docusaurus-openapi-docs/main/demo/examples/petstore.yaml",
241+
hideSendButton: false,
242+
showSchemas: true,
243+
disableCompression: true,
244+
},
245+
cos: {
246+
specPath: "examples/openapi-cos.json",
247+
outputDir: "docs/cos",
248+
sidebarOptions: {
249+
groupPathsBy: "tag",
250+
},
251+
},
252+
burgers: {
253+
specPath: "examples/food/burgers/openapi.yaml",
254+
outputDir: "docs/food/burgers",
255+
},
256+
yogurt: {
257+
specPath: "examples/food/yogurtstore/openapi.yaml",
258+
outputDir: "docs/food/yogurtstore",
259+
},
260+
restaurant: {
261+
specPath: "examples/food/restaurant/openapi.yaml",
262+
outputDir: "docs/restaurant",
263+
sidebarOptions: {
264+
groupPathsBy: "tagGroup",
265+
},
266+
},
267+
},
268+
},
269+
],
270+
],
271+
themes: ["docusaurus-theme-openapi-docs"],
272+
stylesheets: [
273+
{
274+
href: "https://use.fontawesome.com/releases/v5.11.0/css/all.css",
275+
type: "text/css",
276+
},
277+
],
278+
};
279+
280+
async function createConfig() {
281+
const lightTheme = (await import("./src/utils/prismLight.mjs")).default;
282+
const darkTheme = (await import("./src/utils/prismDark.mjs")).default;
283+
// @ts-expect-error: we know it exists, right
284+
config.themeConfig.prism.theme = lightTheme;
285+
// @ts-expect-error: we know it exists, right
286+
config.themeConfig.prism.darkTheme = darkTheme;
287+
return config;
288+
}
289+
290+
module.exports = createConfig;

‎packages/docusaurus-plugin-openapi-docs/src/index.ts

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ export default function pluginOpenAPIDocs(
120120
markdownGenerators,
121121
downloadUrl,
122122
sidebarOptions,
123+
disableCompression,
123124
} = options;
124125

125126
// Remove trailing slash before proceeding
@@ -325,9 +326,11 @@ custom_edit_url: null
325326
// const deserialize = (s: any) => {
326327
// return zlib.inflateSync(Buffer.from(s, "base64")).toString();
327328
// };
328-
item.json = zlib
329-
.deflateSync(JSON.stringify(item.api))
330-
.toString("base64");
329+
disableCompression === true
330+
? (item.json = JSON.stringify(item.api))
331+
: (item.json = zlib
332+
.deflateSync(JSON.stringify(item.api))
333+
.toString("base64"));
331334
let infoBasePath = `${outputDir}/${item.infoId}`;
332335
if (docRouteBasePath) {
333336
infoBasePath = `${docRouteBasePath}/${outputDir

‎packages/docusaurus-plugin-openapi-docs/src/options.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ export const OptionsSchema = Joi.object({
3939
sidebarOptions: sidebarOptions,
4040
markdownGenerators: markdownGenerators,
4141
showSchemas: Joi.boolean(),
42+
disableCompression: Joi.boolean(),
4243
version: Joi.string().when("versions", {
4344
is: Joi.exist(),
4445
then: Joi.required(),

‎packages/docusaurus-plugin-openapi-docs/src/types.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ export interface APIOptions {
4747
proxy?: string;
4848
markdownGenerators?: MarkdownGenerator;
4949
showSchemas?: boolean;
50+
disableCompression?: boolean;
5051
}
5152

5253
export interface MarkdownGenerator {

‎packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/index.tsx

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,12 @@ export default function ApiItem(props: Props): JSX.Element {
5656
const { schema } = frontMatter as SchemaFrontMatter;
5757
// decompress and parse
5858
if (api) {
59-
api = JSON.parse(
60-
zlib.inflateSync(Buffer.from(api as any, "base64")).toString()
61-
);
59+
try {
60+
api = JSON.parse(
61+
zlib.inflateSync(Buffer.from(api as any, "base64")).toString()
62+
);
63+
} catch {}
6264
}
63-
6465
const { siteConfig } = useDocusaurusContext();
6566
const themeConfig = siteConfig.themeConfig as ThemeConfig;
6667
const options = themeConfig.api;

0 commit comments

Comments
 (0)