✅ Allow to add annotations for routes for generated client

[miki725]

it would be useful to add annotations which will persist in the generated client similarly to how route can be annotated for the generated docs (e.g. tags)

express-zod-api/example/example.client.ts

Lines 114 to 118 in 602f6f3

	export const jsonEndpoints = {
	"get /v1/user/retrieve": true,
	"post /v1/user/:id": true,
	"post /v1/avatar/upload": true,
	};

currently generated client only has a single js-exported constant jsonEndpoints which enumerates all endpoints where the value is true. it would be nice to be able to add custom annotations to either the same constant or another exported constant with custom metadata about the endpoint the client can take into account when making requests to the api. perhaps something like:

const helloWorldEndpoint = defaultEndpointsFactory.build({
  ...,
  annotations: {
    foo: "bar"
  }
});

[RobinTail]

Hello @miki725 ,

could you please clarify what kind of things could go to such annotations to be useful for the client in order to request the endpoint?

[miki725]

one use-case is when API has different levels of auth. for example most routes use regular API auth token, however some require special API token for staff/admin/etc. as the auth could be enforced by the API, that metadata is not visible to the client via generated types and therefore the client can attempt to make a request even if its guaranteed to fail (e.g. regular user attempting to call admin-only endpoint). by allowing to annotate each route, it can let the client know more information about the endpoint such as auth requirements which cannot be inferred from types alone

[RobinTail]

Thank you for the explanation, @miki725 .

I wouldn't like to add another method for annotations, cause we already have description, tags and security (including scopes). I think it would be too much.

However, from my understanding the problem, I'd like to find a way to export at least tags (and maybe description and security) information into the generated client.

I think that if you tag your endpoints with the required token type, and if this information will be available as a dictionary in the generated client, this might come helpful.

export const endpointTags = {
  "get /v1/user/retrieve": [ "user", "regularToken" ] as const,
  "delete v1/user/:id": [ "user", "adminToken" ] as const,
}

Similar to existing jsonEndpoints const.

I'm going to think on it a bit. Please let me know if I'm missing something.

[RobinTail]

Check this out, @miki725 :
#1099

Would this come handy for your goals?

[miki725]

yes that will def be useful

[RobinTail]

🚀 11.6.0, @miki725

[miki725]

thank you so much for adding the feature and shipping it 🎉