search

ts-spec / tspec

Type-driven API Documentation library. Auto-generating REST API document based on TypeScript types.
https://ts-spec.github.io/tspec/
MIT License
108 stars 5 forks source link

Generated openapi.json caused https://editor.swagger.io/ to generate incomplete html2 document #59

Closed programatix closed 1 month ago

programatix commented 1 month ago

Describe the bug The generated openapi.json caused https://editor.swagger.io/ to generate incomplete html2 document. This is due to operationId value assigned by ts-spec such as,

The root cause of the issue is due to the value containing /, { and }.

To Reproduce Steps to reproduce the behavior:

  1. Follow ts-spec usage guide to generate an openapi.json
  2. Go to https://editor.swagger.io/
  3. Import the openapi.json
  4. Click on Generate Client -> html2
  5. Download and open the generated file
  6. Documentation is incomplete

Expected behavior When used with other tools such as https://editor.swagger.io/, it can generate a complete document. The following is the result after removing all the /, { and } charactes from operationId. Taking the examples given above, they are corrected to the following,

- operationId: TasksApiSpec_post_tasks
- operationId: TasksApiSpec_put_tasks_id

image

Screenshots Currently, generated document is incomplete. It's missing the schema contents and sample codes are not generated. image

Desktop (please complete the following information):

Additional context

programatix commented 1 month ago

I found that I can specify the operationId manually with Tspec.DefineApiSpec, so this issue can be resolved without requiring a fix on tspec. However, it would be good if the auto generated operationId is in accordance to OpenAPI spec.