Skip to content

Latest commit

 

History

History
 
 

openapi

README.md

@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: unknown)
Target

unknown

Parameters
Name Type Description
key valueof string Extension key. Must start with x-
value 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: TypeSpec.OpenAPI.AdditionalInfo)
Target

Namespace

Parameters
Name Type Description
additionalInfo 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 {

}