docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

package/src/theme/ParamsItem/index.tsx

@@ -7,14 +7,15 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { Example } from "@theme/Example";
 import Markdown from "@theme/Markdown";
-import SchemaTabs from "@theme/SchemaTabs";
-import TabItem from "@theme/TabItem";
 /* eslint-disable import/no-extraneous-dependencies*/
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
-import { guard, toString } from "../../markdown/utils";
+import { guard } from "../../markdown/utils";
 
 export interface ExampleObject {
   summary?: string;
@@ -28,7 +29,7 @@ export interface Props {
   param: {
     description: string;
     example: any;
-    examples: Record<string, ExampleObject>;
+    examples: Record<string, ExampleObject> | undefined;
     name: string;
     required: boolean;
     deprecated: boolean;
@@ -39,7 +40,15 @@ export interface Props {
 
 const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
   if (enumDescriptions?.length) {
-    return `| Enum Value | Description |
+    const enumValue = translate({
+      id: OPENAPI_SCHEMA_ITEM.ENUM_VALUE,
+      message: "Enum Value",
+    });
+    const description = translate({
+      id: OPENAPI_SCHEMA_ITEM.ENUM_DESCRIPTION,
+      message: "Description",
+    });
+    return `| ${enumValue} | ${description} |
 | ---- | ----- |
 ${enumDescriptions
   .map((desc) => {
@@ -53,19 +62,14 @@ ${enumDescriptions
 };
 
 function ParamsItem({ param, ...rest }: Props) {
-  const {
-    description,
-    example,
-    examples,
-    name,
-    required,
-    deprecated,
-    enumDescriptions,
-  } = param;
+  const { description, name, required, deprecated, enumDescriptions } = param;
 
   let schema = param.schema;
   let defaultValue: string | undefined;
 
+  let examples = param.examples ?? (schema?.examples as any[] | undefined);
+  let example = param.example ?? schema?.example;
+
   if (!schema) {
     schema = { type: "any" };
   }
@@ -87,11 +91,15 @@ function ParamsItem({ param, ...rest }: Props) {
   ));
 
   const renderSchemaRequired = guard(required, () => (
-    <span className="openapi-schema__required">required</span>
+    <span className="openapi-schema__required">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
+    </span>
   ));
 
   const renderDeprecated = guard(deprecated, () => (
-    <span className="openapi-schema__deprecated">deprecated</span>
+    <span className="openapi-schema__deprecated">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.DEPRECATED, message: "deprecated" })}
+    </span>
   ));
 
   const renderQualifier = guard(getQualifierMessage(schema), (qualifier) => (
@@ -118,7 +126,12 @@ function ParamsItem({ param, ...rest }: Props) {
       if (typeof defaultValue === "string") {
         return (
           <div>
-            <strong>Default value: </strong>
+            <strong>
+              {translate({
+                id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+                message: "Default value:",
+              })}{" "}
+            </strong>
             <span>
               <code>{defaultValue}</code>
             </span>
@@ -127,7 +140,12 @@ function ParamsItem({ param, ...rest }: Props) {
       }
       return (
         <div>
-          <strong>Default value: </strong>
+          <strong>
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+              message: "Default value:",
+            })}{" "}
+          </strong>
           <span>
             <code>{JSON.stringify(defaultValue)}</code>
           </span>
@@ -137,40 +155,6 @@ function ParamsItem({ param, ...rest }: Props) {
     return undefined;
   }
 
-  const renderExample = guard(toString(example), (example) => (
-    <div>
-      <strong>Example: </strong>
-      {example}
-    </div>
-  ));
-
-  const renderExamples = guard(examples, (examples) => {
-    const exampleEntries = Object.entries(examples);
-    return (
-      <>
-        <strong>Examples:</strong>
-        <SchemaTabs>
-          {exampleEntries.map(([exampleName, exampleProperties]) => (
-            // @ts-ignore
-            <TabItem value={exampleName} label={exampleName}>
-              {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
-              {exampleProperties.description && (
-                <p>
-                  <strong>Description: </strong>
-                  <span>{exampleProperties.description}</span>
-                </p>
-              )}
-              <p>
-                <strong>Example: </strong>
-                <code>{exampleProperties.value}</code>
-              </p>
-            </TabItem>
-          ))}
-        </SchemaTabs>
-      </>
-    );
-  });
-
   return (
     <div className="openapi-params__list-item">
       <span className="openapi-schema__container">
@@ -192,8 +176,8 @@ function ParamsItem({ param, ...rest }: Props) {
       {renderDescription}
       {renderEnumDescriptions}
       {renderDefaultValue()}
-      {renderExample}
-      {renderExamples}
+      <Example example={example} />
+      <Example examples={examples} />
     </div>
   );
 }

package/src/theme/RequestSchema/index.tsx

@@ -7,6 +7,9 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { OPENAPI_REQUEST, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
+
 import BrowserOnly from "@docusaurus/BrowserOnly";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
@@ -64,10 +67,16 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
                   <>
                     <summary>
                       <h3 className="openapi-markdown__details-summary-header-body">
-                        {title}
+                        {translate({
+                          id: OPENAPI_REQUEST.BODY_TITLE,
+                          message: title,
+                        })}
                         {body.required === true && (
                           <span className="openapi-schema__required">
-                            required
+                            {translate({
+                              id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                              message: "required",
+                            })}
                           </span>
                         )}
                       </h3>
@@ -114,13 +123,19 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
             <>
               <summary>
                 <h3 className="openapi-markdown__details-summary-header-body">
-                  {title}
+                  {translate({
+                    id: OPENAPI_REQUEST.BODY_TITLE,
+                    message: title,
+                  })}
                   {firstBody.type === "array" && (
                     <span style={{ opacity: "0.6" }}> array</span>
                   )}
                   {body.required && (
                     <strong className="openapi-schema__required">
-                      required
+                      {translate({
+                        id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                        message: "required",
+                      })}
                     </strong>
                   )}
                 </h3>

package/src/theme/ResponseExamples/index.tsx

@@ -7,9 +7,11 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import CodeSamples from "@theme/CodeSamples";
 import Markdown from "@theme/Markdown";
 import TabItem from "@theme/TabItem";
+import { OPENAPI_RESPONSE_EXAMPLES } from "@theme/translationIds";
 import { sampleResponseFromSchema } from "docusaurus-plugin-openapi-docs/lib/openapi/createResponseExample";
 import format from "xml-formatter";
 
@@ -111,7 +113,13 @@ export const ResponseExample: React.FC<ResponseExampleProps> = ({
 
   return (
     // @ts-ignore
-    <TabItem label="Example" value="Example">
+    <TabItem
+      label={translate({
+        id: OPENAPI_RESPONSE_EXAMPLES.EXAMPLE,
+        message: "Example",
+      })}
+      value="Example"
+    >
       {responseExample.summary && (
         <Markdown className="openapi-example__summary">
           {responseExample.summary}
@@ -163,7 +171,13 @@ export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
       }
       return (
         // @ts-ignore
-        <TabItem label="Example (auto)" value="Example (auto)">
+        <TabItem
+          label={translate({
+            id: OPENAPI_RESPONSE_EXAMPLES.AUTO_EXAMPLE,
+            message: "Example (auto)",
+          })}
+          value="Example (auto)"
+        >
           <CodeSamples example={xmlExample} language="xml" />
         </TabItem>
       );
@@ -176,7 +190,13 @@ export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
   ) {
     return (
       // @ts-ignore
-      <TabItem label="Example (auto)" value="Example (auto)">
+      <TabItem
+        label={translate({
+          id: OPENAPI_RESPONSE_EXAMPLES.AUTO_EXAMPLE,
+          message: "Example (auto)",
+        })}
+        value="Example (auto)"
+      >
         <CodeSamples
           example={JSON.stringify(responseExample, null, 2)}
           language="json"

package/src/theme/ResponseSchema/index.tsx

@@ -8,6 +8,7 @@
 import React from "react";
 
 import BrowserOnly from "@docusaurus/BrowserOnly";
+import { translate } from "@docusaurus/Translate";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
 import MimeTabs from "@theme/MimeTabs"; // Assume these components exist
@@ -20,6 +21,7 @@ import SchemaNode from "@theme/Schema";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
+import { OPENAPI_SCHEMA, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import { MediaTypeObject } from "docusaurus-plugin-openapi-docs/lib/openapi/types";
 
 interface Props {
@@ -54,76 +56,86 @@ const ResponseSchemaComponent: React.FC<Props> = ({
     return (
       <MimeTabs className="openapi-tabs__mime" schemaType="response">
         {mimeTypes.map((mimeType: any) => {
-          const responseExamples = body.content![mimeType].examples;
-          const responseExample = body.content![mimeType].example;
-          const firstBody: any =
-            body.content![mimeType].schema ?? body.content![mimeType];
+          const mediaTypeObject = body.content?.[mimeType];
+          const responseExamples = mediaTypeObject?.examples;
+          const responseExample = mediaTypeObject?.example;
+          const firstBody = mediaTypeObject?.schema;
 
           if (
-            firstBody === undefined &&
-            responseExample === undefined &&
-            responseExamples === undefined
+            !firstBody ||
+            (firstBody.properties &&
+              Object.keys(firstBody.properties).length === 0)
           ) {
-            return undefined;
-          }
-
-          if (firstBody) {
             return (
               // @ts-ignore
               <TabItem key={mimeType} label={mimeType} value={mimeType}>
-                <SchemaTabs className="openapi-tabs__schema">
-                  {/* @ts-ignore */}
-                  <TabItem key={title} label={title} value={title}>
-                    <Details
-                      className="openapi-markdown__details response"
-                      data-collapsed={false}
-                      open={true}
-                      style={style}
-                      summary={
-                        <>
-                          <summary>
-                            <strong className="openapi-markdown__details-summary-response">
-                              {title}
-                              {body.required === true && (
-                                <span className="openapi-schema__required">
-                                  required
-                                </span>
-                              )}
-                            </strong>
-                          </summary>
-                        </>
-                      }
-                    >
-                      <div style={{ textAlign: "left", marginLeft: "1rem" }}>
-                        {body.description && (
-                          <div
-                            style={{ marginTop: "1rem", marginBottom: "1rem" }}
-                          >
-                            <Markdown>{body.description}</Markdown>
-                          </div>
-                        )}
-                      </div>
-                      <ul style={{ marginLeft: "1rem" }}>
-                        <SchemaNode schema={firstBody} schemaType="response" />
-                      </ul>
-                    </Details>
-                  </TabItem>
-                  {firstBody &&
-                    ExampleFromSchema({
-                      schema: firstBody,
-                      mimeType: mimeType,
-                    })}
-
-                  {responseExamples &&
-                    ResponseExamples({ responseExamples, mimeType })}
-
-                  {responseExample &&
-                    ResponseExample({ responseExample, mimeType })}
-                </SchemaTabs>
+                <div>
+                  {translate({
+                    id: OPENAPI_SCHEMA.NO_SCHEMA,
+                    message: "No schema",
+                  })}
+                </div>
               </TabItem>
             );
           }
-          return undefined;
+
+          return (
+            // @ts-ignore
+            <TabItem key={mimeType} label={mimeType} value={mimeType}>
+              <SchemaTabs className="openapi-tabs__schema">
+                {/* @ts-ignore */}
+                <TabItem key={title} label={title} value={title}>
+                  <Details
+                    className="openapi-markdown__details response"
+                    data-collapsed={false}
+                    open={true}
+                    style={style}
+                    summary={
+                      <>
+                        <summary>
+                          <strong className="openapi-markdown__details-summary-response">
+                            {title}
+                            {body.required === true && (
+                              <span className="openapi-schema__required">
+                                {translate({
+                                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                  message: "required",
+                                })}
+                              </span>
+                            )}
+                          </strong>
+                        </summary>
+                      </>
+                    }
+                  >
+                    <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                      {body.description && (
+                        <div
+                          style={{ marginTop: "1rem", marginBottom: "1rem" }}
+                        >
+                          <Markdown>{body.description}</Markdown>
+                        </div>
+                      )}
+                    </div>
+                    <ul style={{ marginLeft: "1rem" }}>
+                      <SchemaNode schema={firstBody} schemaType="response" />
+                    </ul>
+                  </Details>
+                </TabItem>
+                {firstBody &&
+                  ExampleFromSchema({
+                    schema: firstBody,
+                    mimeType: mimeType,
+                  })}
+
+                {responseExamples &&
+                  ResponseExamples({ responseExamples, mimeType })}
+
+                {responseExample &&
+                  ResponseExample({ responseExample, mimeType })}
+              </SchemaTabs>
+            </TabItem>
+          );
         })}
       </MimeTabs>
     );