Provide a decorator or other means to specify OpenAPI tag properties

[mikekistler]

OpenAPI v2 and v3 support a global "tags" property that associates additional properties -- a description and link to external docs -- with a tag name.

https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#tag-object

Many popular doc generators will display the information in these properties in the generated docs.

TypeSpec should provide a means to populate these properties for any tags used in the API definition.

[markcowl]

How should we augment the tags decorator to allow additional metadata?

[decarufe]

Is there a plan to implement this soon?

[bterlson]

Proposal: add a new decorator to the OpenAPI library called tagMetadata. It MUST be applied to the service namespace, it is an error if it is applied to any other type. Multiple applications of tagMetadata merge like tag. The decorator takes a tag name and a model of additional properties, so for example:

@service
@tagMetadata("pet", { description: "Pets operations", externalDocs: { url: "https://example.com", description: "More info." } });
namespace PetStore;

We know we want to disambiguate data values from types via #{ ... } syntax, however OpenAPI is already rife with this ambiguity (e.g. with @extension and @info), so there doesn't seem to be much harm in continuing this trend for now.

[johanste]

I assume multiple instances will merge?

[bterlson]

Yes, like @tag. Updated.