Add support for @pattern, @format, @nullable

[robogeek]

Description

The OpenAPI spec I'm working with has pattern, nullable, and format attributes all over the place, and these are not turned into JSDOC tags.

Other tools, like @openapi-codegen/cli, support these tags.

JSDOC tags are used by other tools like ts-to-zod and @savotije/openapi-to-joi, each of which generate schema validation code from TYpeScript source. Both of those recognize @pattern, @nullable and @format tags.

Proposal

I don't really understand the code, but I found some simple changes in addJSDocComment would suffice.

First, I added a pattern field in AnnotatedSchemaObject:

export interface AnnotatedSchemaObject {
  const?: unknown; // jsdoc without value
  default?: unknown; // jsdoc with value
  deprecated?: boolean; // jsdoc without value
  description?: string; // jsdoc with value
  enum?: unknown[]; // jsdoc without value
  example?: string; // jsdoc with value
  format?: string; // not jsdoc
  pattern?: string; // not jsdoc
  nullable?: boolean; // Node information
  summary?: string; // not jsdoc
  title?: string; // not jsdoc
  type?: string | string[]; // Type of node
}

Then, I commented out the test for schemaObject.format.

Then, I changed supportedJsDocTags to this:

  const supportedJsDocTags = [
    "description", "default", "example", 'pattern', 'format'
  ] as const;

Finally, I added the following:

  if ('nullable' in schemaObject) {
    output.push(`@nullable ${schemaObject.nullable ? 'true' : 'false'}`);
  }

These changes supported the tags I mentioned, and generated JSDoc tags that look correct to me.

Checklist

• I’m willing to open a PR for this (see CONTRIBUTING.md)

[robogeek]

This is a diff for the changes I made
diff.txt

[htunnicliff]

@drwpow thoughts on this?

[drwpow]

I’d accept a PR for this! This should be easy to add, and we already have some tools we use to generate these JS Doc comments. It should be simple to insert the @nullable tag in there.