search

ferdikoomen / openapi-typescript-codegen

NodeJS library that generates Typescript or Javascript clients based on the OpenAPI specification
MIT License
2.88k stars 519 forks source link

Richer JSDoc in output library #967

Open maciejgoscinski opened 2 years ago

maciejgoscinski commented 2 years ago

Hello! I love the codegen so far, we use it in our large scale serverless project in the following scenario:

  1. Typescript Backend with TSOA Controllers
  2. generated OpenApi3 Spec with rich documentation and validations
  3. generated frontend typescript client (and other language clients)

Generated code matches the initial structure really well, preserving complex union types (Dog | Cat), understanding interface extension, etc. What it doesn't (obviously) do, is help with validation rules such as min/maxLengths.

It would be non-intrusively helpful if we could optionally preserve the JSDoc structure that we used in the original code to generate OpenAPI rich spec. Or, more closely, generate rich JSDoc from the OpenAPI descriptions.

Our initial annotations (as well as the "target" JSDoc we'd like to have in the generated client).

/**
 * @minLength 0
 * @maxLength 150
 */
export type Address_Note = string;

which corresponds to the following in the OpenApi.json

  "Address_Note": {
  "type": "string",
  "minLength": 0,
  "maxLength": 150
  },

If data from OpenAPI spec, such as example, minLength, pattern, description from both Schemas and Operations, could be mapped in the output to JSDoc comments above interfaces, services, properties, etc, we could preserve rich information about the proper data structure and see it in IntelliSense-like way in the IDEs.

ferdikoomen commented 2 years ago

@maciejgoscinski Sounds like a logical request, feel free to create a PR, or otherwise i'll put it on the roadmap