From e157c956aa3bafad47d7555e19fe571f40a41f6a Mon Sep 17 00:00:00 2001 From: Baptiste Arnaud Date: Tue, 22 Nov 2022 11:12:37 +0100 Subject: [PATCH 1/2] Hide required labels on response schemas --- .../src/markdown/createSchemaTable.ts | 50 +++++++++++++++---- .../src/markdown/createStatusCodesTable.ts | 3 ++ 2 files changed, 43 insertions(+), 10 deletions(-) diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts b/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts index a006a9c9..7ee764fc 100644 --- a/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts +++ b/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts @@ -34,13 +34,25 @@ function resolveAllOf(allOf: SchemaObject[]) { return { properties, required }; } +interface RowOptions { + showRequiredLabel?: boolean; +} + +const defaultRowOptions: RowOptions = { showRequiredLabel: true }; + interface RowProps { name: string; schema: SchemaObject; required: boolean; + options?: RowOptions; } -function createRow({ name, schema, required }: RowProps) { +function createRow({ + name, + schema, + required, + options = defaultRowOptions, +}: RowProps) { return create("tr", { children: create("td", { children: [ @@ -49,7 +61,7 @@ function createRow({ name, schema, required }: RowProps) { style: { opacity: "0.6" }, children: ` ${getSchemaName(schema, true)}`, }), - guard(required, () => [ + guard(required && options.showRequiredLabel, () => [ create("span", { style: { opacity: "0.6" }, children: " — ", @@ -74,7 +86,7 @@ function createRow({ name, schema, required }: RowProps) { children: createDescription(description), }) ), - createRows({ schema: schema }), + createRows({ schema: schema, options }), ], }), }); @@ -82,9 +94,13 @@ function createRow({ name, schema, required }: RowProps) { interface RowsProps { schema: SchemaObject; + options?: RowOptions; } -function createRows({ schema }: RowsProps): string | undefined { +function createRows({ + schema, + options = defaultRowOptions, +}: RowsProps): string | undefined { // object if (schema.properties !== undefined) { return createFullWidthTable({ @@ -100,6 +116,7 @@ function createRows({ schema }: RowsProps): string | undefined { required: Array.isArray(schema.required) ? schema.required.includes(key) : false, + options, }) ), }), @@ -120,6 +137,7 @@ function createRows({ schema }: RowsProps): string | undefined { name: key, schema: val, required: Array.isArray(required) ? required.includes(key) : false, + options, }) ), }), @@ -128,7 +146,7 @@ function createRows({ schema }: RowsProps): string | undefined { // array if (schema.items !== undefined) { - return createRows({ schema: schema.items }); + return createRows({ schema: schema.items, options }); } // primitive @@ -137,9 +155,13 @@ function createRows({ schema }: RowsProps): string | undefined { interface RowsRootProps { schema: SchemaObject; + options?: RowOptions; } -function createRowsRoot({ schema }: RowsRootProps) { +function createRowsRoot({ + schema, + options = defaultRowOptions, +}: RowsRootProps) { // object if (schema.properties !== undefined) { return Object.entries(schema.properties).map(([key, val]) => @@ -149,6 +171,7 @@ function createRowsRoot({ schema }: RowsRootProps) { required: Array.isArray(schema.required) ? schema.required.includes(key) : false, + options, }) ); } @@ -161,6 +184,7 @@ function createRowsRoot({ schema }: RowsRootProps) { name: key, schema: val, required: Array.isArray(required) ? required.includes(key) : false, + options, }) ); } @@ -174,7 +198,7 @@ function createRowsRoot({ schema }: RowsRootProps) { style: { opacity: "0.6" }, children: ` ${getSchemaName(schema, true)}`, }), - createRows({ schema: schema.items }), + createRows({ schema: schema.items, options }), ], }), }); @@ -215,9 +239,15 @@ interface Props { description?: string; required?: boolean; }; + options?: RowOptions; } -export function createSchemaTable({ title, body, ...rest }: Props) { +export function createSchemaTable({ + title, + body, + options = defaultRowOptions, + ...rest +}: Props) { if (body === undefined || body.content === undefined) { return undefined; } @@ -249,7 +279,7 @@ export function createSchemaTable({ title, body, ...rest }: Props) { style: { textAlign: "left" }, children: [ `${title} `, - guard(body.required, () => [ + guard(body.required && options.showRequiredLabel, () => [ create("span", { style: { opacity: "0.6" }, children: " — ", @@ -270,7 +300,7 @@ export function createSchemaTable({ title, body, ...rest }: Props) { }), }), create("tbody", { - children: createRowsRoot({ schema: firstBody }), + children: createRowsRoot({ schema: firstBody, options }), }), ], }); diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts b/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts index e39732f9..c0757adf 100644 --- a/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts +++ b/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts @@ -64,6 +64,9 @@ export function createStatusCodesTable({ responses }: Props) { body: { content: responses[code].content, }, + options: { + showRequiredLabel: false, + }, }), }), ], From f5dc5f72e96000dbe19b75bdbeb3120fad94faa7 Mon Sep 17 00:00:00 2001 From: Baptiste Arnaud Date: Mon, 28 Nov 2022 17:18:15 +0100 Subject: [PATCH 2/2] Add Optional label in response schemas --- .../src/markdown/createRequestBodyTable.ts | 2 +- .../src/markdown/createSchemaTable.ts | 119 ++++++++---------- .../src/markdown/createStatusCodesTable.ts | 4 +- .../src/theme/ApiPage/styles.module.css | 2 + 4 files changed, 57 insertions(+), 70 deletions(-) diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createRequestBodyTable.ts b/packages/docusaurus-plugin-openapi/src/markdown/createRequestBodyTable.ts index e99442a4..19db5ce3 100644 --- a/packages/docusaurus-plugin-openapi/src/markdown/createRequestBodyTable.ts +++ b/packages/docusaurus-plugin-openapi/src/markdown/createRequestBodyTable.ts @@ -13,5 +13,5 @@ interface Props { } export function createRequestBodyTable({ title, body }: Props) { - return createSchemaTable({ title, body }); + return createSchemaTable({ title, body, type: "request" }); } diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts b/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts index 7ee764fc..adc7da93 100644 --- a/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts +++ b/packages/docusaurus-plugin-openapi/src/markdown/createSchemaTable.ts @@ -34,25 +34,14 @@ function resolveAllOf(allOf: SchemaObject[]) { return { properties, required }; } -interface RowOptions { - showRequiredLabel?: boolean; -} - -const defaultRowOptions: RowOptions = { showRequiredLabel: true }; - interface RowProps { name: string; schema: SchemaObject; required: boolean; - options?: RowOptions; + type: "request" | "response"; } -function createRow({ - name, - schema, - required, - options = defaultRowOptions, -}: RowProps) { +function createRow({ name, schema, required, type }: RowProps) { return create("tr", { children: create("td", { children: [ @@ -61,19 +50,7 @@ function createRow({ style: { opacity: "0.6" }, children: ` ${getSchemaName(schema, true)}`, }), - guard(required && options.showRequiredLabel, () => [ - create("span", { - style: { opacity: "0.6" }, - children: " — ", - }), - create("strong", { - style: { - fontSize: "var(--ifm-code-font-size)", - color: "var(--openapi-required)", - }, - children: " REQUIRED", - }), - ]), + ...parseTitleLabel({ required, type }), guard(getQualifierMessage(schema), (message) => create("div", { style: { marginTop: "var(--ifm-table-cell-padding)" }, @@ -86,21 +63,17 @@ function createRow({ children: createDescription(description), }) ), - createRows({ schema: schema, options }), + createRows({ schema: schema, type }), ], }), }); } -interface RowsProps { +interface RowsProps extends Pick { schema: SchemaObject; - options?: RowOptions; } -function createRows({ - schema, - options = defaultRowOptions, -}: RowsProps): string | undefined { +function createRows({ schema, type }: RowsProps): string | undefined { // object if (schema.properties !== undefined) { return createFullWidthTable({ @@ -116,7 +89,7 @@ function createRows({ required: Array.isArray(schema.required) ? schema.required.includes(key) : false, - options, + type, }) ), }), @@ -137,7 +110,7 @@ function createRows({ name: key, schema: val, required: Array.isArray(required) ? required.includes(key) : false, - options, + type, }) ), }), @@ -146,22 +119,18 @@ function createRows({ // array if (schema.items !== undefined) { - return createRows({ schema: schema.items, options }); + return createRows({ schema: schema.items, type }); } // primitive return undefined; } -interface RowsRootProps { +interface RowsRootProps extends Pick { schema: SchemaObject; - options?: RowOptions; } -function createRowsRoot({ - schema, - options = defaultRowOptions, -}: RowsRootProps) { +function createRowsRoot({ schema, type }: RowsRootProps) { // object if (schema.properties !== undefined) { return Object.entries(schema.properties).map(([key, val]) => @@ -171,7 +140,7 @@ function createRowsRoot({ required: Array.isArray(schema.required) ? schema.required.includes(key) : false, - options, + type, }) ); } @@ -184,7 +153,7 @@ function createRowsRoot({ name: key, schema: val, required: Array.isArray(required) ? required.includes(key) : false, - options, + type, }) ); } @@ -198,7 +167,7 @@ function createRowsRoot({ style: { opacity: "0.6" }, children: ` ${getSchemaName(schema, true)}`, }), - createRows({ schema: schema.items, options }), + createRows({ schema: schema.items, type }), ], }), }); @@ -239,15 +208,10 @@ interface Props { description?: string; required?: boolean; }; - options?: RowOptions; + type: "request" | "response"; } -export function createSchemaTable({ - title, - body, - options = defaultRowOptions, - ...rest -}: Props) { +export function createSchemaTable({ title, body, type, ...rest }: Props) { if (body === undefined || body.content === undefined) { return undefined; } @@ -279,19 +243,7 @@ export function createSchemaTable({ style: { textAlign: "left" }, children: [ `${title} `, - guard(body.required && options.showRequiredLabel, () => [ - create("span", { - style: { opacity: "0.6" }, - children: " — ", - }), - create("strong", { - style: { - fontSize: "var(--ifm-code-font-size)", - color: "var(--openapi-required)", - }, - children: " REQUIRED", - }), - ]), + ...parseTitleLabel({ required: body.required, type }), create("div", { children: createDescription(body.description), }), @@ -300,8 +252,43 @@ export function createSchemaTable({ }), }), create("tbody", { - children: createRowsRoot({ schema: firstBody, options }), + children: createRowsRoot({ schema: firstBody, type }), }), ], }); } + +const parseTitleLabel = ({ + required, + type, +}: { + required?: boolean; + type: Props["type"]; +}) => [ + guard(required && type === "request", () => [ + create("span", { + style: { opacity: "0.6" }, + children: " — ", + }), + create("strong", { + style: { + fontSize: "var(--ifm-code-font-size)", + color: "var(--openapi-required)", + }, + children: " REQUIRED", + }), + ]), + guard(!required && type === "response", () => [ + create("span", { + style: { opacity: "0.6" }, + children: " — ", + }), + create("strong", { + style: { + fontSize: "var(--ifm-code-font-size)", + color: "var(--openapi-optional)", + }, + children: " OPTIONAL", + }), + ]), +]; diff --git a/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts b/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts index c0757adf..e16b13b1 100644 --- a/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts +++ b/packages/docusaurus-plugin-openapi/src/markdown/createStatusCodesTable.ts @@ -64,9 +64,7 @@ export function createStatusCodesTable({ responses }: Props) { body: { content: responses[code].content, }, - options: { - showRequiredLabel: false, - }, + type: "response", }), }), ], diff --git a/packages/docusaurus-theme-openapi/src/theme/ApiPage/styles.module.css b/packages/docusaurus-theme-openapi/src/theme/ApiPage/styles.module.css index 8e3652ad..7cd672ab 100644 --- a/packages/docusaurus-theme-openapi/src/theme/ApiPage/styles.module.css +++ b/packages/docusaurus-theme-openapi/src/theme/ApiPage/styles.module.css @@ -33,6 +33,7 @@ --api-sidebar-hidden-width: 30px; --openapi-required: var(--openapi-code-red); + --openapi-optional: var(--openapi-code-dim); --openapi-card-background-color: #f6f8fa; --openapi-card-border-radius: var(--ifm-pre-border-radius); @@ -62,6 +63,7 @@ html[data-theme="dark"] { --openapi-monaco-border-color: #606770; --openapi-required: var(--openapi-code-red); + --openapi-optional: var(--openapi-code-dim); --openapi-card-background-color: var(--ifm-card-background-color);