Skip to content

Latest commit

 

History

History
 
 

openapi

Cadl OpenAPI Library

This package provide Cadl decorators to specify some OpenAPI specific concepts.

Install

In your cadl project root

npm install @cadl-lang/openapi

Usage

import "@cadl-lang/openapi";

using OpenAPI;

References

Decorators:

@defaultResponse

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;

@extension

This decorator lets you sepecify 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 {}

@externalDocs

Decorator that can be used to provide the externalDocs property on OpenAPI elements. OpenAPI spec for extenalDocs

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 {}

@operationId

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 cadl operation name.

Arguments:

Name foo Description
opId Required Id of the operation
@operationId("custom_Foo")
op foo(): string;

See also