support "deprecated" annotations

[sakari]

migrating apis would would be nicer if we could advertise that something is deprecated

type level

In the generated types that something is // @deprecated

• for generated endpoints we can mark the endpoint call in the type as deprecated
• for generated data types we can mark all of NamedType, typeNamedType, etc. Will this though cause spurious warnings when we refer to those things from elsewhere in the generated code
• how to say an enumeration value is deprecated?
• how to say a field of an object is deprecated?

A converse of depracation is saying something will become mandatory -- so a new field added might be marked as "soon this will be mandatory". That can ofc be marked by creating a copy of the object schema with the new field present and marking the original as deprecated. Doing that by hand, given the support openapi has for sharing base definitions, might be a bit tedious though.

Runtime

Usage of deprecated things might result in configurable warnings so that the clients and servers can monitor when no more deprecated things are coming from clients before moving on. On client side might be nice to have that -- however the deprecation warning should already come from the typechecker