Parse .describe as markdown with yaml front matter

[razor-x]

Parse Zod description as Markdown with YAML front matter: https://jekyllrb.com/docs/front-matter/
This is a well established system for including metadata inside a plain markdown string.

The front matter would be included in the openapi spec as metadata while the body would be used as the description. Some keys can trigger special behavior, for example injecting @deprecated into the generated types.

For example:

const routeSpec = {
  methods: ["POST"],
  auth: "auth_token",
  jsonBody: z.object({
    name: z.string().describe(`
    ---
    deprecated: Use full_name
    ---
    The name of the user.
    `),
    full_name: z.string().describe("The name of the user."),
  }),
  jsonResponse: z.object({
    ok: z.boolean(),
  }),
} as const

[razor-x]

This comes close to solving the issue of "how do I mark a field in a zod schema deprecated". The field will be marked deprecated in the generated route types, but there is still no way to mark the deprecation in the inferred type, e.g.,

const user = z.object({
  name: z.string(),
  full_name: z.string(),
})

const User = z.infer<user>

const u: User = { name: "a", full_name: "b" }

// would like if u.name could be flagged as deprecated by the typescript LSP / VSCode, etc.

See colinhacks/zod#3028

[razor-x]

cc @codetheweb @seveibar

[phpnode]

added a PR to add support for this to @anatine/zod-openapi, let's see what they say. Plan B would be to walk the generated output and parse it ourselves, but that's a bit messier