feat: document deprecated properties in schemas

cypress-io · Jun 1, 2018 · 4c235fc · 4c235fc
1 parent 1d06370
commit 4c235fc
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 30 deletions.
diff --git a/src/document/utils.ts b/src/document/utils.ts
@@ -107,6 +107,8 @@ export const documentProperties = (
     : Object.keys(properties)
   const isRequired = name => requiredProperties.indexOf(name) !== -1
   const typeText = type => (Array.isArray(type) ? type.join(' or ') : type)
+  const deprecatedMessage = (value: JsonProperty) =>
+    value.deprecated ? `**deprecated** ${value.deprecated}` : emptyMark
 
   return Object.keys(properties)
     .sort()
@@ -119,6 +121,7 @@ export const documentProperties = (
         format: formatToMarkdown(schemas, formats)(value),
         enum: enumToMarkdown(value.enum),
         description: value.description ? value.description : emptyMark,
+        deprecated: deprecatedMessage(value),
       }
     })
 }
@@ -144,6 +147,7 @@ export const documentSchema = (
       'format',
       'enum',
       'description',
+      'deprecated',
     ]
     const usedHeaders = findUsedColumns(headers, rows)
     const table: object[] = [

diff --git a/test/document-test.ts b/test/document-test.ts
@@ -189,6 +189,39 @@ test('document deprecated schema', t => {
     },
   }
   const result = json2md(documentObjectSchema(schema))
-  // console.log(result)
+  t.snapshot(result)
+})
+
+test('document deprecated schema property', t => {
+  t.plan(1)
+  const jsonSchema: JsonSchema = {
+    title: 'testSchema',
+    type: 'object',
+    additionalProperties: true,
+    description: 'This is a test schema',
+    properties: {
+      id: {
+        type: 'string',
+      },
+      name: {
+        type: 'string',
+        enum: ['joe', 'mary'],
+        deprecated: 'use property "fullName" instead',
+      },
+    },
+  }
+  const schema: ObjectSchema = {
+    version: {
+      major: 1,
+      minor: 2,
+      patch: 3,
+    },
+    schema: jsonSchema,
+    example: {
+      id: 'abc',
+      name: 'joe',
+    },
+  }
+  const result = json2md(documentObjectSchema(schema))
   t.snapshot(result)
 })
diff --git a/test/snapshots/document-test.ts.md b/test/snapshots/document-test.ts.md
@@ -4,34 +4,6 @@ The actual snapshot is saved in `document-test.ts.snap`.
 
 Generated by [AVA](https://ava.li).
 
-## document deprecated schema
-
-> Snapshot 1
-
-    `### testSchema@1.2.3␊
-    ␊
-    ␊
-    This is a test schema␊
-    ␊
-    ␊
-    **deprecated** no longer in use␊
-    ␊
-    name | type | enum␊
-    --- | --- | ---␊
-    `id` | string | ␊
-    `name` | string | `"joe", "mary"`␊
-    ␊
-    ␊
-    Example:␊
-    ␊
-    ```json␊
-    {␊
-      "id": "abc",␊
-      "name": "joe"␊
-    }␊
-    ```␊
-
-
 ## JSON schema object to Markdown
 
 > Snapshot 1
@@ -55,6 +27,7 @@ Generated by [AVA](https://ava.li).
           ],
           rows: [
             {
+              deprecated: '',
               description: '',
               enum: '',
               format: '',
@@ -63,6 +36,7 @@ Generated by [AVA](https://ava.li).
               type: 'string',
             },
             {
+              deprecated: '',
               description: '',
               enum: '',
               format: '',
@@ -127,12 +101,69 @@ Generated by [AVA](https://ava.li).
     my-foo | `/^foo$/`␊
     `
 
+## document deprecated schema
+
+> Snapshot 1
+
+    `### testSchema@1.2.3␊
+    ␊
+    ␊
+    This is a test schema␊
+    ␊
+    ␊
+    **deprecated** no longer in use␊
+    ␊
+    name | type | enum␊
+    --- | --- | ---␊
+    `id` | string | ␊
+    `name` | string | `"joe", "mary"`␊
+    ␊
+    ␊
+    Example:␊
+    ␊
+    ```json␊
+    {␊
+      "id": "abc",␊
+      "name": "joe"␊
+    }␊
+    ```␊
+    `
+
+## document deprecated schema property
+
+> Snapshot 1
+
+    `### testSchema@1.2.3␊
+    ␊
+    ␊
+    This is a test schema␊
+    ␊
+    name | type | enum | deprecated␊
+    --- | --- | --- | ---␊
+    `id` | string |  | ␊
+    `name` | string | `"joe", "mary"` | **deprecated** use property "fullName" instead␊
+    ␊
+    ␊
+    This schema allows additional properties.␊
+    ␊
+    ␊
+    Example:␊
+    ␊
+    ```json␊
+    {␊
+      "id": "abc",␊
+      "name": "joe"␊
+    }␊
+    ```␊
+    `
+
 ## document properties
 
 > Snapshot 1
 
     [
       {
+        deprecated: '',
         description: 'Can only be choice a or b',
         enum: '`"A", "B"`',
         format: '',
@@ -141,6 +172,7 @@ Generated by [AVA](https://ava.li).
         type: 'string',
       },
       {
+        deprecated: '',
         description: 'Property foo',
         enum: '',
         format: '',
@@ -308,4 +340,4 @@ Generated by [AVA](https://ava.li).
          - inner level 1␊
          - inner level 2␊
         ␊
-    `
+    `
diff --git a/test/snapshots/document-test.ts.snap b/test/snapshots/document-test.ts.snap