Skip to content

Latest commit

 

History

History
 
 

openapi

README.md

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