Write a specification of your endpoints in TypeScript, and from that one spec you get:
- Server side validation of requests/responses
- A TypeScript API client
- Specialized clients, if you like, for example a react-query client if you like using react-query
- Auto-generated docs (OAS)
- TypeScript types for requests and responses to use in your code
IMO a lot more maintainable than a jsdoc based approach. For example, you can define a type for a Person, and then re-use that type in the responses of all Person-related endpoints, and even in POST/PUT/PATCH bodies (saying things like “the POST body is a person Person, but omit the id field”). With jsdoc you’re repeating that definition a tonne, AND you’re lacking compile time type safety.
Personally I’m a fan of ts-rest: https://ts-rest.com/
Write a specification of your endpoints in TypeScript, and from that one spec you get:
- Server side validation of requests/responses
- A TypeScript API client
- Specialized clients, if you like, for example a react-query client if you like using react-query
- Auto-generated docs (OAS)
- TypeScript types for requests and responses to use in your code
IMO a lot more maintainable than a jsdoc based approach. For example, you can define a type for a Person, and then re-use that type in the responses of all Person-related endpoints, and even in POST/PUT/PATCH bodies (saying things like “the POST body is a person Person, but omit the id field”). With jsdoc you’re repeating that definition a tonne, AND you’re lacking compile time type safety.