[Enhancement] Add deprecated support to schema items (#367)

* Include deprecated in markdown schema item

* Hide deprecated schema items from examples

* Add deprecated and strikethrough styles and conditionally render

* Revert petstore.yaml to original

Author: sserrata

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

@@ -597,6 +597,7 @@ function createEdges({
       collapsible: false,
       name,
       required: Array.isArray(required) ? required.includes(name) : required,
+      deprecated: mergedSchemas.deprecated,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
@@ -630,6 +631,7 @@ function createEdges({
     collapsible: false,
     name,
     required: Array.isArray(required) ? required.includes(name) : required,
+    deprecated: schema.deprecated,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),

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

@@ -597,6 +597,7 @@ function createEdges({
       collapsible: false,
       name,
       required: false,
+      deprecated: mergedSchemas.deprecated,
       schemaDescription: mergedSchemas.description,
       schemaName: schemaName,
       qualifierMessage: getQualifierMessage(schema),
@@ -630,6 +631,7 @@ function createEdges({
     collapsible: false,
     name,
     required: false,
+    deprecated: schema.deprecated,
     schemaDescription: schema.description,
     schemaName: schemaName,
     qualifierMessage: getQualifierMessage(schema),

packages/docusaurus-plugin-openapi-docs/src/openapi/createRequestExample.ts

@@ -98,7 +98,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
         mergeAllOf(allOf);
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-          if (value.readOnly && value.readOnly === true) {
+          if ((value.readOnly && value.readOnly === true) || value.deprecated) {
             delete mergedSchemas.properties[key];
           }
         }
@@ -121,15 +121,21 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
       for (let [name, prop] of Object.entries(properties ?? {})) {
         if (prop.properties) {
           for (const [key, value] of Object.entries(prop.properties)) {
-            if (value.readOnly && value.readOnly === true) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.properties[key];
             }
           }
         }
 
         if (prop.items && prop.items.properties) {
           for (const [key, value] of Object.entries(prop.items.properties)) {
-            if (value.readOnly && value.readOnly === true) {
+            if (
+              (value.readOnly && value.readOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.items.properties[key];
             }
           }
@@ -168,7 +174,7 @@ export const sampleRequestFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
-    if (schema.readOnly && schema.readOnly === true) {
+    if ((schema.readOnly && schema.readOnly === true) || schema.deprecated) {
       return undefined;
     }
 

packages/docusaurus-plugin-openapi-docs/src/openapi/createResponseExample.ts

@@ -88,7 +88,10 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
         mergeAllOf(allOf);
       if (mergedSchemas.properties) {
         for (const [key, value] of Object.entries(mergedSchemas.properties)) {
-          if (value.writeOnly && value.writeOnly === true) {
+          if (
+            (value.writeOnly && value.writeOnly === true) ||
+            value.deprecated
+          ) {
             delete mergedSchemas.properties[key];
           }
         }
@@ -121,15 +124,21 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
       for (let [name, prop] of Object.entries(properties ?? {})) {
         if (prop.properties) {
           for (const [key, value] of Object.entries(prop.properties)) {
-            if (value.writeOnly && value.writeOnly === true) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.properties[key];
             }
           }
         }
 
         if (prop.items && prop.items.properties) {
           for (const [key, value] of Object.entries(prop.items.properties)) {
-            if (value.writeOnly && value.writeOnly === true) {
+            if (
+              (value.writeOnly && value.writeOnly === true) ||
+              value.deprecated
+            ) {
               delete prop.items.properties[key];
             }
           }
@@ -168,7 +177,7 @@ export const sampleResponseFromSchema = (schema: SchemaObject = {}): any => {
       return normalizeArray(schema.enum)[0];
     }
 
-    if (schema.writeOnly && schema.writeOnly === true) {
+    if ((schema.writeOnly && schema.writeOnly === true) || schema.deprecated) {
       return undefined;
     }
 

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

@@ -23,6 +23,7 @@ function SchemaItem({
   name,
   qualifierMessage,
   required,
+  deprecated,
   schemaDescription,
   schemaName,
   defaultValue,
@@ -32,6 +33,10 @@ function SchemaItem({
     () => <strong className={styles.required}> required</strong>
   );
 
+  const renderDeprecated = guard(deprecated, () => (
+    <strong className={styles.deprecated}> deprecated</strong>
+  ));
+
   const renderSchemaDescription = guard(schemaDescription, (description) => (
     <div>
       <ReactMarkdown
@@ -73,9 +78,10 @@ function SchemaItem({
 
   const schemaContent = (
     <div>
-      <strong>{name}</strong>
+      <strong className={deprecated && styles.strikethrough}>{name}</strong>
       <span className={styles.schemaName}> {schemaName}</span>
-      {renderRequired}
+      {!deprecated && renderRequired}
+      {renderDeprecated}
       {renderQualifierMessage}
       {renderDefaultValue}
       {renderSchemaDescription}

packages/docusaurus-theme-openapi-docs/src/theme/SchemaItem/styles.module.css

@@ -22,3 +22,12 @@
   font-size: var(--ifm-code-font-size);
   color: var(--openapi-required);
 }
+
+.deprecated {
+  font-size: var(--ifm-code-font-size);
+  color: var(--openapi-deprecated);
+}
+
+.strikethrough {
+  text-decoration: line-through;
+}

packages/docusaurus-theme-openapi-docs/src/theme/styles.css

@@ -7,6 +7,7 @@
 
 :root {
   --openapi-required: var(--ifm-color-danger);
+  --openapi-deprecated: var(--ifm-color-warning);
   --openapi-code-blue: var(--ifm-color-info);
   --openapi-code-red: var(--ifm-color-danger);
   --openapi-code-orange: var(--ifm-color-warning);