Decorators

TypeSpec.OpenAPI

@defaultResponse

Specify that this model is to be treated as the OpenAPI default response. This differs from the compiler built-in @error decorator as this does not necessarily represent an error.

@TypeSpec.OpenAPI.defaultResponse

Target

Model

Parameters

None

Examples

@defaultResponse
model PetStoreResponse is object;

op listPets(): Pet[] | PetStoreResponse;

@extension

Attach some custom data to the OpenAPI element generated from this type.

@TypeSpec.OpenAPI.extension(key: valueof string, value: valueof unknown)

Target

unknown

Parameters

Name	Type	Description
key	valueof string	Extension key.
value	valueof unknown	Extension value.

Examples

@extension("x-custom", "My value")
@extension("x-pageable", #{ nextLink: "x-next-link" })
op read(): string;

@externalDocs

Specify the OpenAPI externalDocs property for this type.

@TypeSpec.OpenAPI.externalDocs(url: valueof string, description?: valueof string)

Target

unknown

Parameters

Name	Type	Description
url	valueof string	Url to the docs
description	valueof string	Description of the docs

Examples

@externalDocs(
  "https://example.com/detailed.md",
  "Detailed information on how to use this operation"
)
op listPets(): Pet[];

@info

Specify OpenAPI additional information. The service title is already specified using @service.

@TypeSpec.OpenAPI.info(additionalInfo: valueof TypeSpec.OpenAPI.AdditionalInfo)

Target

Namespace

Parameters

Name	Type	Description
additionalInfo	valueof AdditionalInfo	Additional information

@operationId

Specify the OpenAPI operationId property for this operation.

@TypeSpec.OpenAPI.operationId(operationId: valueof string)

Target

Operation

Parameters

Name	Type	Description
operationId	valueof string	Operation id value.

Examples

@operationId("download")
op read(): string;

@tagMetadata

Specify OpenAPI tag metadata. Can be used in two forms:

• Inline form: specify a single tag by name with optional metadata.
• Array form: specify an ordered list of tags with their metadata in a single decorator call.

@TypeSpec.OpenAPI.tagMetadata(name: valueof string | TypeSpec.OpenAPI.TagMetadataWithName[], tagMetadata?: valueof TypeSpec.OpenAPI.TagMetadata)

Target

Namespace

Parameters

Name	Type	Description
name	valueof string | TypeSpec.OpenAPI.TagMetadataWithName[]	Tag name (inline form) or array of tags with metadata (array form).
tagMetadata	valueof TagMetadata	Additional information for the tag. Only used in inline form.

Examples

Inline form

@service
@tagMetadata(
  "Tag Name",
  #{
    description: "Tag description",
    externalDocs: #{ url: "https://example.com", description: "More info.", `x-custom`: "string" },
    `x-custom`: "string",
  }
)
@tagMetadata("Child Tag", #{ description: "Child tag description", parent: "Tag Name" })
namespace PetStore {

}

Array form (preserves explicit tag order)

@service
@tagMetadata(#[
  #{ name: "First Tag", description: "First tag description" },
  #{ name: "Second Tag", description: "Second tag description" }
])
namespace PetStore {

}