@typespec/openapi
TypeSpec library providing OpenAPI concepts
Install
npm install @typespec/openapi copy
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 copy
Target
Model
Parameters
None
Examples
@defaultResponse
model PetStoreResponse is object ;
op listPets () : Pet [] | PetStoreResponse ; copy
@extension
Attach some custom data to the OpenAPI element generated from this type.
@TypeSpec.OpenAPI.extension ( key : valueof string , value : valueof unknown ) copy
Target
unknown
Parameters
Name Type Description key valueof stringExtension key. value valueof unknownExtension value.
Examples
@extension ( "x-custom" , "My value" )
@extension ( "x-pageable" , #{ nextLink : "x-next-link" })
op read () : string ; copy
@externalDocs
Specify the OpenAPI externalDocs property for this type.
@TypeSpec.OpenAPI.externalDocs ( url : valueof string , description ?: valueof string ) copy
Target
unknown
Parameters
Name Type Description url valueof stringUrl to the docs description valueof stringDescription of the docs
Examples
@externalDocs (
"https://example.com/detailed.md" ,
"Detailed information on how to use this operation"
)
op listPets () : Pet []; copy
@info
Specify OpenAPI additional information.
The service title is already specified using @service.
@TypeSpec.OpenAPI.info ( additionalInfo : valueof TypeSpec . OpenAPI . AdditionalInfo ) copy
Target
Namespace
Parameters
@operationId
Specify the OpenAPI operationId property for this operation.
@TypeSpec.OpenAPI.operationId ( operationId : valueof string ) copy
Target
Operation
Parameters
Name Type Description operationId valueof stringOperation id value.
Examples
@operationId ( "download" )
op read () : string ; copy
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 ) copy
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
@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 {
} copy
@service
@tagMetadata (#[
#{ name : "First Tag" , description : "First tag description" },
#{ name : "Second Tag" , description : "Second tag description" }
])
namespace PetStore {
} copy