docusaurus-theme-openapi-docs 4.5.1 → 4.7.0

package/src/theme/SchemaItem/index.tsx

@@ -7,7 +7,10 @@
 
 import React, { ReactNode } from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { Example } from "@theme/Example";
 import Markdown from "@theme/Markdown";
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 import { guard } from "../../markdown/utils";
@@ -36,7 +39,15 @@ const transformEnumDescriptions = (
 
 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) => {
@@ -63,6 +74,7 @@ export default function SchemaItem(props: Props) {
   let schemaDescription;
   let defaultValue: string | undefined;
   let example: string | undefined;
+  let examples: string[] | undefined;
   let nullable;
   let enumDescriptions: [string, string][] = [];
   let constValue: string | undefined;
@@ -73,6 +85,7 @@ export default function SchemaItem(props: Props) {
     enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
     example = schema.example;
+    examples = schema.examples;
     nullable =
       schema.nullable ||
       (Array.isArray(schema.type) && schema.type.includes("null")); // support JSON Schema nullable
@@ -81,15 +94,23 @@ export default function SchemaItem(props: Props) {
 
   const renderRequired = guard(
     Array.isArray(required) ? required.includes(name) : 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 renderNullable = guard(nullable, () => (
-    <span className="openapi-schema__nullable">nullable</span>
+    <span className="openapi-schema__nullable">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.NULLABLE, message: "nullable" })}
+    </span>
   ));
 
   const renderEnumDescriptions = guard(
@@ -120,7 +141,12 @@ export default function SchemaItem(props: 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>
@@ -129,7 +155,12 @@ export default function SchemaItem(props: 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>
@@ -139,36 +170,17 @@ export default function SchemaItem(props: Props) {
     return undefined;
   }
 
-  function renderExample() {
-    if (example !== undefined) {
-      if (typeof example === "string") {
-        return (
-          <div>
-            <strong>Example: </strong>
-            <span>
-              <code>{example}</code>
-            </span>
-          </div>
-        );
-      }
-      return (
-        <div>
-          <strong>Example: </strong>
-          <span>
-            <code>{JSON.stringify(example)}</code>
-          </span>
-        </div>
-      );
-    }
-    return undefined;
-  }
-
   function renderConstValue() {
     if (constValue !== undefined) {
       if (typeof constValue === "string") {
         return (
           <div>
-            <strong>Constant value: </strong>
+            <strong>
+              {translate({
+                id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+                message: "Constant value:",
+              })}{" "}
+            </strong>
             <span>
               <code>{constValue}</code>
             </span>
@@ -177,7 +189,12 @@ export default function SchemaItem(props: Props) {
       }
       return (
         <div>
-          <strong>Constant value: </strong>
+          <strong>
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+              message: "Constant value:",
+            })}{" "}
+          </strong>
           <span>
             <code>{JSON.stringify(constValue)}</code>
           </span>
@@ -212,7 +229,8 @@ export default function SchemaItem(props: Props) {
       {renderQualifierMessage}
       {renderConstValue()}
       {renderDefaultValue()}
-      {renderExample()}
+      <Example example={example} />
+      <Example examples={examples} />
       {collapsibleSchemaContent ?? collapsibleSchemaContent}
     </div>
   );

package/src/theme/SchemaTabs/index.tsx

@@ -25,13 +25,22 @@ import useIsBrowser from "@docusaurus/useIsBrowser";
 import clsx from "clsx";
 import flatten from "lodash/flatten";
 
+export interface SchemaTabsProps extends TabProps {
+  /**
+   * Optional callback fired when the selected tab changes.
+   * Receives the index of the newly selected tab.
+   */
+  onChange?: (index: number) => void;
+}
+
 function TabList({
   className,
   block,
   selectedValue,
   selectValue,
   tabValues,
-}: TabProps & ReturnType<typeof useTabs>) {
+  onChange,
+}: SchemaTabsProps & ReturnType<typeof useTabs>) {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
@@ -49,6 +58,8 @@ function TabList({
     if (newTabValue !== selectedValue) {
       blockElementScrollPositionUntilNextRender(newTab);
       selectValue(newTabValue);
+      // Notify parent component of the tab change
+      onChange?.(newTabIndex);
     }
   };
 
@@ -115,7 +126,10 @@ function TabList({
   };
 
   return (
-    <div className="openapi-tabs__schema-tabs-container">
+    <div
+      className="openapi-tabs__schema-tabs-container"
+      style={{ marginBottom: "1rem" }}
+    >
       {showTabArrows && (
         <button
           className="openapi-tabs__arrow left"
@@ -174,7 +188,7 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: TabProps & ReturnType<typeof useTabs>) {
+}: SchemaTabsProps & ReturnType<typeof useTabs>) {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -200,7 +214,7 @@ function TabContent({
     </div>
   );
 }
-function TabsComponent(props: TabProps): React.JSX.Element {
+function TabsComponent(props: SchemaTabsProps): React.JSX.Element {
   const tabs = useTabs(props);
   return (
     <div className="openapi-tabs__schema-container">
@@ -209,7 +223,7 @@ function TabsComponent(props: TabProps): React.JSX.Element {
     </div>
   );
 }
-export default function SchemaTabs(props: TabProps): React.JSX.Element {
+export default function SchemaTabs(props: SchemaTabsProps): React.JSX.Element {
   const isBrowser = useIsBrowser();
   return (
     <TabsComponent

package/src/theme/StatusCodes/index.tsx

@@ -7,13 +7,15 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import ApiTabs from "@theme/ApiTabs";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
 import ResponseHeaders from "@theme/ResponseHeaders";
 import ResponseSchema from "@theme/ResponseSchema";
 import TabItem from "@theme/TabItem";
-import { ApiItem } from "docusaurus-plugin-openapi-docs/lib/types";
+import { OPENAPI_STATUS_CODES } from "@theme/translationIds";
+import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 
 interface Props {
   id?: string;
@@ -51,7 +53,12 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
                 style={{ textAlign: "left", marginBottom: "1rem" }}
                 summary={
                   <summary>
-                    <strong>Response Headers</strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_STATUS_CODES.RESPONSE_HEADERS,
+                        message: "Response Headers",
+                      })}
+                    </strong>
                   </summary>
                 }
               >
@@ -59,7 +66,10 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
               </Details>
             )}
             <ResponseSchema
-              title="Schema"
+              title={translate({
+                id: OPENAPI_STATUS_CODES.SCHEMA_TITLE,
+                message: "Schema",
+              })}
               body={{ content: response.content }}
             />
           </TabItem>

package/src/theme/styles.scss

@@ -41,6 +41,8 @@
 @use "./CodeSamples/CodeSamples";
 /* Markdown Styling */
 @use "./Markdown/Details/Details";
+/* Example Styling */
+@use "./Example/Example";
 
 :root {
   --openapi-required: var(--ifm-color-danger);
@@ -67,6 +69,9 @@
   --openapi-code-tab-border-color-java: #0374bd;
   --openapi-code-tab-border-color-powershell: #00adef;
   --openapi-code-tab-shadow-color-python: rgba(255, 219, 80, 0.25);
+  --openapi-code-tab-shadow-color-curl: var(
+    --openapi-code-tab-shadow-color-bash
+  );
   --openapi-code-tab-shadow-color-bash: rgba(250, 56, 62, 0.25);
   --openapi-code-tab-shadow-color-go: rgba(84, 199, 236, 0.25);
   --openapi-code-tab-shadow-color-js: rgba(255, 186, 0, 0.25);
@@ -161,6 +166,16 @@
   border-right: thin solid var(--ifm-toc-border-color);
 }
 
+@media (min-width: 997px) {
+  .openapi-right-panel__container {
+    position: sticky;
+    top: calc(var(--ifm-navbar-height) + 1rem);
+    max-height: calc(100vh - var(--ifm-navbar-height) - 2rem);
+    overflow-y: auto;
+    align-self: flex-start;
+  }
+}
+
 @media (max-width: 997px) {
   .schema {
     margin-bottom: 1rem;

package/src/theme/translationIds.ts

@@ -0,0 +1,111 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+export const OPENAPI_RESPONSE = {
+  TITLE: "theme.openapi.response.title",
+  CLEAR: "theme.openapi.response.clear",
+  PLACEHOLDER: "theme.openapi.response.placeholder",
+  HEADERS_TAB: "theme.openapi.response.headersTab",
+};
+
+export const OPENAPI_TABS = {
+  RESPONSES_LABEL: "theme.openapi.tabs.responses.label",
+};
+
+export const OPENAPI_REQUEST = {
+  BODY_TITLE: "theme.openapi.request.body.title",
+  ACCEPT_TITLE: "theme.openapi.request.accept.title",
+  SEND_BUTTON: "theme.openapi.request.sendButton",
+  REQUIRED_LABEL: "theme.openapi.request.requiredLabel",
+  REQUEST_TITLE: "theme.openapi.request.title",
+  COLLAPSE_ALL: "theme.openapi.request.collapseAll",
+  EXPAND_ALL: "theme.openapi.request.expandAll",
+  BASE_URL_TITLE: "theme.openapi.request.baseUrl.title",
+  AUTH_TITLE: "theme.openapi.request.auth.title",
+  PARAMETERS_TITLE: "theme.openapi.request.parameters.title",
+  FETCHING_MESSAGE: "theme.openapi.request.fetchingMessage",
+  CONNECTION_FAILED: "theme.openapi.request.connectionFailed",
+  ERROR_TIMEOUT: "theme.openapi.request.error.timeout",
+  ERROR_NETWORK: "theme.openapi.request.error.network",
+  ERROR_CORS: "theme.openapi.request.error.cors",
+  ERROR_UNKNOWN: "theme.openapi.request.error.unknown",
+};
+
+export const OPENAPI_SERVER = {
+  EDIT_BUTTON: "theme.openapi.server.editButton",
+  HIDE_BUTTON: "theme.openapi.server.hideButton",
+};
+
+export const OPENAPI_PARAM_OPTIONS = {
+  SHOW_OPTIONAL: "theme.openapi.paramOptions.showOptional",
+  HIDE_OPTIONAL: "theme.openapi.paramOptions.hideOptional",
+};
+
+export const OPENAPI_FORM_FILE_UPLOAD = {
+  CLEAR_BUTTON: "theme.openapi.formFileUpload.clearButton",
+};
+
+export const OPENAPI_FORM = {
+  FIELD_REQUIRED: "theme.openapi.form.fieldRequired",
+};
+
+export const OPENAPI_AUTH = {
+  BEARER_TOKEN: "theme.openapi.auth.bearerToken",
+  USERNAME: "theme.openapi.auth.username",
+  PASSWORD: "theme.openapi.auth.password",
+  SECURITY_SCHEME: "theme.openapi.auth.securityScheme",
+};
+
+export const OPENAPI_RESPONSE_EXAMPLES = {
+  EXAMPLE: "theme.openapi.responseExamples.example",
+  AUTO_EXAMPLE: "theme.openapi.responseExamples.autoExample",
+};
+
+export const OPENAPI_BODY = {
+  EXAMPLE_FROM_SCHEMA: "theme.openapi.body.exampleFromSchema",
+};
+
+export const OPENAPI_STATUS_CODES = {
+  RESPONSE_HEADERS: "theme.openapi.statusCodes.responseHeaders",
+  SCHEMA_TITLE: "theme.openapi.statusCodes.schemaTitle",
+};
+
+export const OPENAPI_SCHEMA = {
+  NO_SCHEMA: "theme.openapi.schema.noSchema",
+};
+
+export const OPENAPI_SCHEMA_ITEM = {
+  REQUIRED: "theme.openapi.schemaItem.required",
+  DEPRECATED: "theme.openapi.schemaItem.deprecated",
+  NULLABLE: "theme.openapi.schemaItem.nullable",
+  DEFAULT_VALUE: "theme.openapi.schemaItem.defaultValue",
+  EXAMPLE: "theme.openapi.schemaItem.example",
+  EXAMPLES: "theme.openapi.schemaItem.examples",
+  DESCRIPTION: "theme.openapi.schemaItem.description",
+  CONSTANT_VALUE: "theme.openapi.schemaItem.constantValue",
+  ENUM_VALUE: "theme.openapi.schemaItem.enumValue",
+  ENUM_DESCRIPTION: "theme.openapi.schemaItem.enumDescription",
+  POSSIBLE_VALUES: "theme.openapi.schemaItem.possibleValues",
+  ONE_OF: "theme.openapi.schemaItem.oneOf",
+  ANY_OF: "theme.openapi.schemaItem.anyOf",
+};
+
+export const OPENAPI_PARAMS_DETAILS = {
+  PARAMETERS_TITLE: "theme.openapi.paramsDetails.parametersTitle",
+};
+
+export const OPENAPI_SECURITY_SCHEMES = {
+  NAME: "theme.openapi.securitySchemes.name",
+  TYPE: "theme.openapi.securitySchemes.type",
+  SCOPES: "theme.openapi.securitySchemes.scopes",
+  IN: "theme.openapi.securitySchemes.in",
+  FLOWS: "theme.openapi.securitySchemes.flows",
+  DESCRIPTION: "theme.openapi.securitySchemes.description",
+  SCHEME: "theme.openapi.securitySchemes.scheme",
+  BEARER_FORMAT: "theme.openapi.securitySchemes.bearerFormat",
+  OPEN_ID_CONNECT_URL: "theme.openapi.securitySchemes.openIdConnectUrl",
+};