[bugfix] Ensure 0 and false are guarded correctly and add deprecated support to params (#754)

* avoid guarding 0 values

* support deprecated params

* update utils tests to should guard false

* always render required when true and apply strikethrough when deprecated

Author: sserrata

packages/docusaurus-plugin-openapi-docs/src/markdown/utils.ts

@@ -38,7 +38,7 @@ export function guard<T>(
   value: T | undefined,
   cb: (value: T) => Children
 ): string {
-  if (!!value) {
+  if (!!value || value === 0) {
     const children = cb(value);
     return render(children);
   }

packages/docusaurus-theme-openapi-docs/src/markdown/utils.test.ts

@@ -22,6 +22,11 @@ describe("guard", () => {
     expect(actual).toBe("");
   });
 
+  it("should guard false booleans", () => {
+    const actual = guard(false, (value) => `${value}`);
+    expect(actual).toBe("");
+  });
+
   it("should not guard strings", () => {
     const actual = guard("hello", (value) => value);
     expect(actual).toBe("hello");
@@ -37,10 +42,6 @@ describe("guard", () => {
     expect(actual).toBe("0");
   });
 
-  it("should not guard false booleans", () => {
-    const actual = guard(false, (value) => `${value}`);
-    expect(actual).toBe("false");
-  });
   it("should not guard true booleans", () => {
     const actual = guard(true, (value) => `${value}`);
     expect(actual).toBe("true");

packages/docusaurus-theme-openapi-docs/src/markdown/utils.ts

@@ -26,11 +26,11 @@ export function guard<T>(
   value: T | undefined | string,
   cb: (value: T) => Children
 ): string {
-  if (value === undefined || value === "") {
-    return "";
+  if (!!value || value === 0) {
+    const children = cb(value as T);
+    return render(children);
   }
-  const children = cb(value as T);
-  return render(children);
+  return "";
 }
 
 export function render(children: Children): string {

packages/docusaurus-theme-openapi-docs/src/theme/ParamsItem/index.tsx

@@ -10,6 +10,19 @@ import React from "react";
 import CodeBlock from "@theme/CodeBlock";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
+/* eslint-disable import/no-extraneous-dependencies*/
+import clsx from "clsx";
+import { createDescription } from "docusaurus-theme-openapi-docs/lib/markdown/createDescription";
+/* eslint-disable import/no-extraneous-dependencies*/
+import {
+  getQualifierMessage,
+  getSchemaName,
+} from "docusaurus-theme-openapi-docs/lib/markdown/schema";
+/* eslint-disable import/no-extraneous-dependencies*/
+import {
+  guard,
+  toString,
+} from "docusaurus-theme-openapi-docs/lib/markdown/utils";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
 
@@ -40,7 +53,7 @@ export interface Props {
 }
 
 function ParamsItem({
-  param: { description, example, examples, name, required, schema },
+  param: { description, example, examples, name, required, schema, deprecated },
 }: Props) {
   if (!schema || !schema?.type) {
     schema = { type: "any" };
@@ -54,6 +67,10 @@ function ParamsItem({
     <span className="openapi-schema__required">required</span>
   ));
 
+  const renderDeprecated = guard(deprecated, () => (
+    <span className="openapi-schema__deprecated">deprecated</span>
+  ));
+
   const renderSchema = guard(getQualifierMessage(schema), (message) => (
     <div>
       <ReactMarkdown
@@ -134,10 +151,19 @@ function ParamsItem({
   return (
     <div className="openapi-params__list-item">
       <span className="openapi-schema__container">
-        <strong className="openapi-schema__property">{name}</strong>
+        <strong
+          className={clsx("openapi-schema__property", {
+            "openapi-schema__strikethrough": deprecated,
+          })}
+        >
+          {name}
+        </strong>
         {renderSchemaName}
-        {required && <span className="openapi-schema__divider"></span>}
+        {(required || deprecated) && (
+          <span className="openapi-schema__divider"></span>
+        )}
         {renderSchemaRequired}
+        {renderDeprecated}
       </span>
       {renderSchema}
       {renderDefaultValue}

packages/docusaurus-theme-openapi-docs/src/theme/SchemaItem/index.tsx

@@ -111,7 +111,7 @@ export default function SchemaItem({
           <span className="openapi-schema__divider"></span>
         )}
         {renderNullable}
-        {!deprecated && renderRequired}
+        {renderRequired}
         {renderDeprecated}
       </span>
       {renderQualifierMessage}