This package provide TypeSpec decorators to specify some OpenAPI specific concepts.
In your typespec project root
npm install @typespec/openapiimport "@typespec/openapi";
using OpenAPI;
Decorators:
IMPORTANT This is to be used on NON-ERROR responses that cover all the other status codes. If you are looking to represent an error use @error
Decorator that can be used on a response model to specify the default status code that OpenAPI allow.
@defaultResponse
model MyNonErrorResponse {}
op foo(): MyNonErrorResponse;
This decorator lets you specify custom key(starting with x-) value pair that will be added to the OpenAPI document.
OpenAPI reference on extensions
Arguments:
| Name | foo | Description |
|---|---|---|
key |
Required | Extension key. MUST start with x- |
value |
Required | Value of the extension. Can be an primitive, a tuple or a model. |
@extension("x-custom", "MyCustomValue")
model Foo {}
// Value can be an model.
@extension(
"x-custom",
{
some: "value",
}
)
model Foo {}
Decorator that can be used to provide the externalDocs property on OpenAPI elements.
OpenAPI spec for externalDocs
Arguments:
| Name | foo | Description |
|---|---|---|
url |
Required | Url for the external docs |
description |
Optional | Description of the documentation |
@externalDocs("https://example.com", "More info there")
model Foo {}
Decorator that can be used on an operation to specify the operationId field in OpenAPI. If this is not provided the operationId will be the typespec operation name.
Arguments:
| Name | foo | Description |
|---|---|---|
opId |
Required | Id of the operation |
@operationId("custom_Foo")
op foo(): string;