feat(Markdown): markdown support for single, 1-depth responses

Author: jaychang99

src/utils/format-single-api-endpoint-as-markdown.ts

@@ -1,5 +1,6 @@
+import { OpenAPIV3 } from 'openapi-types'
 import { CustomPathDiffItem } from './generate-markdown-diff'
-import { jsonToMarkdown } from './json-to-markdown'
+import { SchemaObject, jsonToMarkdown } from './json-to-markdown'
 
 type FormatSingleApiEndpointAsMarkdown = (
   endpoint: CustomPathDiffItem
@@ -25,13 +26,17 @@ export const formatSingleApiEndpointAsMarkdown: FormatSingleApiEndpointAsMarkdow
   endpoint => {
     const { url, method, endpointDetailData } = endpoint
     const { responses } = endpointDetailData
-    const successResponse = responses['200'] ?? responses['201']
-    const successResponseContent = isReferenceObject(successResponse)
-      ? {}
-      : successResponse?.content?.['application/json'] ??
-        successResponse?.content?.['text/plain']
-
-    const responseMarkdown = jsonToMarkdown(successResponseContent)
+    const successResponse = (responses['200'] ??
+      responses['201']) as OpenAPIV3.ResponseObject // all refs have been resolved in main.ts
+    const successResponseContent =
+      successResponse?.content?.['application/json'] ??
+      successResponse?.content?.['text/plain']
+    const successResponseContentSchema =
+      successResponseContent?.schema as SchemaObject
+
+    const responseMarkdown = successResponseContent?.schema
+      ? jsonToMarkdown({ schema: successResponseContentSchema })
+      : ''
 
     const parameterMarkdownArray = Object.entries(
       endpointDetailData.parameters ?? {}
@@ -69,7 +74,7 @@ ${responseMarkdown}
 
 `
 
-    console.log(generatedMarkdown)
+    // console.log(generatedMarkdown)
 
     return generatedMarkdown
   }

src/utils/json-to-markdown.ts

@@ -1,25 +1,79 @@
 // Utility function to format JSON as Markdown code block
 
+import { OpenAPIV3 } from 'openapi-types'
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function jsonToMarkdown(obj: any, depth = 0): string {
-  let md = depth === 0 ? '```markdown\n' : '' // Start code block only at the top level
-  const indent = '  '.repeat(depth)
-
-  for (const key in obj) {
-    if (
-      typeof obj[key] === 'object' &&
-      obj[key] !== null &&
-      !Array.isArray(obj[key])
-    ) {
-      md += `${indent} ${key} :\n`
-      md += jsonToMarkdown(obj[key], depth + 1) // Recursively append sub-objects
-    } else {
-      md += `${indent}- ${key}: ${JSON.stringify(obj[key], null, 2)}\n`
-    }
+
+export type SchemaObject = ArraySchemaObject | NonArraySchemaObject
+interface ArraySchemaObject extends CustomBaseSchemaObject {
+  type: OpenAPIV3.ArraySchemaObjectType
+  items: SchemaObject // All refs are resolved in main.ts before calling this function
+}
+interface NonArraySchemaObject extends CustomBaseSchemaObject {
+  type?: OpenAPIV3.NonArraySchemaObjectType
+}
+interface CustomBaseSchemaObject {
+  title?: string
+  description?: string
+  format?: string
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  default?: any
+  multipleOf?: number
+  maximum?: number
+  exclusiveMaximum?: boolean
+  minimum?: number
+  exclusiveMinimum?: boolean
+  maxLength?: number
+  minLength?: number
+  pattern?: string
+  additionalProperties?: boolean | SchemaObject
+  maxItems?: number
+  minItems?: number
+  uniqueItems?: boolean
+  maxProperties?: number
+  minProperties?: number
+  required?: string[]
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  enum?: any[]
+  properties?: {
+    [name: string]: SchemaObject
   }
+  allOf?: SchemaObject[]
+  oneOf?: SchemaObject[]
+  anyOf?: SchemaObject[]
+  not?: SchemaObject
+  nullable?: boolean
+  discriminator?: OpenAPIV3.DiscriminatorObject
+  readOnly?: boolean
+  writeOnly?: boolean
+  xml?: OpenAPIV3.XMLObject
+  externalDocs?: OpenAPIV3.ExternalDocumentationObject
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  example?: any
+  deprecated?: boolean
+}
+
+export type SingleReponseObj = {
+  schema: SchemaObject
+}
 
-  if (depth === 0) {
-    md += '```\n' // End code block only at the top level
+// recursively format nested objects until obj.type is not 'object' , 'array' , null or undefined
+// WRITE YOUR CODE HERE
+
+export function jsonToMarkdown(obj: SingleReponseObj): string {
+  const properties = obj.schema.properties
+
+  if (!properties) return ''
+
+  let md = '```markdown\n'
+
+  for (const property of Object.entries(properties)) {
+    const [propertyName, propertyMetadata] = property
+
+    md += `${propertyName} : ${propertyMetadata.type}; \n📎${propertyMetadata.description} \n📚EX) ${propertyMetadata.example} \n\n`
   }
+
+  md += '```'
+
   return md
 }