feat: document deprecated schema, close #64

src/document/docs.ts

@@ -1,11 +1,8 @@
 // generates Markdown document with all schema information
 
-import stringify from 'json-stable-stringify'
 import json2md from 'json2md'
-import quote from 'quote'
 import { flatten } from 'ramda'
 import {
-  getExample,
   getObjectSchema,
   getSchemaVersions,
   normalizeName,
@@ -14,9 +11,9 @@ import {
 import { CustomFormats } from '../formats'
 import { ObjectSchema, SchemaCollection } from '../objects'
 import { documentCustomFormats } from './doc-formats'
-import { anchor, documentSchema } from './utils'
+import { anchor, documentObjectSchema } from './utils'
 
-const ticks = quote({ quotes: '`' })
+// const ticks = quote({ quotes: '`' })
 const title = [{ h1: 'Schemas' }]
 const titleLink = [{ p: '[🔝](#schemas)' }]
 
@@ -46,36 +43,15 @@ export function documentSchemas(
         throw new Error(`cannot find schema ${schemaName}@${version}`)
       }
 
-      const schemaDoc = documentSchema(schema.schema, schemas, formats)
+      const schemaDoc = documentObjectSchema(schema, schemas, formats)
 
-      const start: any[] = [{ h3: `${schemaName}@${version}` }]
-      if (schema.package) {
-        start.push({
-          p: `Defined in ${ticks(schema.package)}`,
-        })
-      }
-      if (schema.schema.description) {
-        start.push({ p: schema.schema.description })
-      }
-
-      const example = getExample(schemas)(schemaName)(version)
-      const exampleFragment = flatten([
-        schemaDoc,
-        { p: 'Example:' },
-        {
-          code: {
-            language: 'json',
-            content: stringify(example, { space: '  ' }),
-          },
-        },
-        titleLink,
-      ])
-      return flatten(start.concat(exampleFragment))
+      return flatten(schemaDoc.concat(titleLink))
     }
 
     const versionFragments = versions.map(documentSchemaVersion)
 
-    return [{ h2: normalizeName(schemaName) }].concat(flatten(versionFragments))
+    const start: object[] = [{ h2: normalizeName(schemaName) }]
+    return start.concat(flatten(versionFragments))
   }
 
   const fragments = flatten(schemaNames(schemas).map(toDoc))
@@ -98,10 +74,6 @@ export function documentSchemas(
     }
   }
 
-  // const extractH2 = map(prop('h2'))
-  // const filterH2 = filter(has('h2'))
-  // const headings = extractH2(filterH2(fragments))
-
   const headings = schemaNames(schemas)
   const toc = [
     {

src/document/utils.ts

@@ -1,5 +1,6 @@
+import stringify from 'json-stable-stringify'
 import quote from 'quote'
-import { find, toLower } from 'ramda'
+import { find, flatten, toLower } from 'ramda'
 import { normalizeName, schemaNames, semverToString } from '..'
 import { CustomFormats } from '../formats'
 import {
@@ -163,3 +164,51 @@ export const documentSchema = (
     return { p: 'Hmm, no properties found in this schema' }
   }
 }
+
+const schemaNameHeading = (name: string, version: string) =>
+  `${name}@${version}`
+
+export const documentObjectSchema = (
+  schema: ObjectSchema,
+  schemas?: SchemaCollection,
+  formats?: CustomFormats,
+) => {
+  const schemaName = schema.schema.title
+
+  if (schemaName.includes(' ')) {
+    throw new Error(`Schema title contains spaces "${schemaName}"
+      This can cause problems generating anchors!`)
+  }
+
+  const schemaVersion = semverToString(schema.version)
+
+  const start: object[] = [{ h3: schemaNameHeading(schemaName, schemaVersion) }]
+  if (schema.package) {
+    start.push({
+      p: `Defined in ${ticks(schema.package)}`,
+    })
+  }
+  if (schema.schema.description) {
+    start.push({ p: schema.schema.description })
+  }
+
+  if (schema.schema.deprecated) {
+    start.push({
+      p: `**deprecated** ${schema.schema.deprecated}`,
+    })
+  }
+
+  const propertiesTable = documentSchema(schema.schema, schemas, formats)
+
+  const exampleFragment = flatten([
+    { p: 'Example:' },
+    {
+      code: {
+        language: 'json',
+        content: stringify(schema.example, { space: '  ' }),
+      },
+    },
+  ])
+
+  return flatten(start.concat(propertiesTable).concat(exampleFragment))
+}

src/objects.ts

@@ -52,6 +52,8 @@ export type JsonProperty = {
   patternProperties?: object
   additionalProperties?: boolean
   enum?: string[]
+  // if the property is deprecated show this message
+  deprecated?: string
 }
 
 export type JsonProperties = {
@@ -69,6 +71,7 @@ export type JsonSchema = {
   required?: string[] | true
   // does the schema allow unknown properties?
   additionalProperties: boolean
+  deprecated?: string
 }
 
 export type ObjectSchema = {

test/document-test.ts

@@ -4,12 +4,13 @@ import { clone } from 'ramda'
 import { documentSchemas, setPackageName } from '../src'
 import { documentCustomFormats } from '../src/document/doc-formats'
 import {
+  documentObjectSchema,
   documentProperties,
   documentSchema,
   findUsedColumns,
 } from '../src/document/utils'
 import { CustomFormats } from '../src/formats'
-import { JsonProperties, JsonSchema } from '../src/objects'
+import { JsonProperties, JsonSchema, ObjectSchema } from '../src/objects'
 import { exampleFormats, schemas } from './example-schemas'
 
 test('documents just schemas', t => {
@@ -156,3 +157,38 @@ test('JSON schema with enumeration to Markdown', t => {
   const result = json2md(documentSchema(schema))
   t.snapshot(result)
 })
+
+test('document deprecated schema', t => {
+  t.plan(1)
+  const jsonSchema: JsonSchema = {
+    title: 'testSchema',
+    type: 'object',
+    additionalProperties: false,
+    description: 'This is a test schema',
+    deprecated: 'no longer in use',
+    properties: {
+      id: {
+        type: 'string',
+      },
+      name: {
+        type: 'string',
+        enum: ['joe', 'mary'],
+      },
+    },
+  }
+  const schema: ObjectSchema = {
+    version: {
+      major: 1,
+      minor: 2,
+      patch: 3,
+    },
+    schema: jsonSchema,
+    example: {
+      id: 'abc',
+      name: 'joe',
+    },
+  }
+  const result = json2md(documentObjectSchema(schema))
+  // console.log(result)
+  t.snapshot(result)
+})

test/snapshots/document-test.ts.md

@@ -4,6 +4,34 @@ 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
@@ -134,7 +162,7 @@ Generated by [AVA](https://ava.li).
     ␊
     ## person␊
     ␊
-    ### person@1.0.0␊
+    ### Person@1.0.0␊
     ␊
     ␊
     An example schema describing a person␊
@@ -159,7 +187,7 @@ Generated by [AVA](https://ava.li).
     ␊
     ## team␊
     ␊
-    ### team@1.0.0␊
+    ### Team@1.0.0␊
     ␊
     ␊
     A team of people␊
@@ -198,7 +226,7 @@ Generated by [AVA](https://ava.li).
     ␊
     ## person␊
     ␊
-    ### person@1.0.0␊
+    ### Person@1.0.0␊
     ␊
     ␊
     An example schema describing a person␊
@@ -223,7 +251,7 @@ Generated by [AVA](https://ava.li).
     ␊
     ## team␊
     ␊
-    ### team@1.0.0␊
+    ### Team@1.0.0␊
     ␊
     ␊
     A team of people␊
@@ -280,4 +308,4 @@ Generated by [AVA](https://ava.li).
          - inner level 1␊
          - inner level 2␊
         ␊
-    `
+    `