Skip to content

Files

openapi

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Feb 28, 2025
Feb 28, 2025
Feb 28, 2025
Feb 28, 2025
Jan 24, 2024
Feb 11, 2025
Feb 28, 2025
Sep 6, 2024
Feb 11, 2025
Jan 22, 2024
Jul 1, 2024
Jan 22, 2024

@typespec/openapi

TypeSpec library providing OpenAPI concepts

Install

npm install @typespec/openapi

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 and version are 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 additional information.

@TypeSpec.OpenAPI.tagMetadata(name: valueof string, tagMetadata: valueof TypeSpec.OpenAPI.TagMetadata)
Target

Namespace

Parameters
Name Type Description
name valueof string tag name
tagMetadata valueof TagMetadata Additional information
Examples
@service
@tagMetadata(
  "Tag Name",
  #{
    description: "Tag description",
    externalDocs: #{ url: "https://example.com", description: "More info.", `x-custom`: "string" },
    `x-custom`: "string",
  }
)
namespace PetStore {

}