This package has been deprecated

Author message:

@cadl-lang packages are deprecated use @typespec instead.

@cadl-lang/openapi3

Cadl OpenAPI 3.0 Emitter

This package provides the Cadl emitter to produce OpenAPI 3.0 output from Cadl source.

Install

In your cadl project root

npm install @cadl-lang/openapi3

Emit OpenAPI 3.0 spec

1. Via the command line

cadl compile . --emit @cadl-lang/openapi3

2. Via the config

Add the following to the cadl-project.yaml file.

emitters:
  @cadl-lang/openapi3: true

For configuration see options

Use OpenAPI 3.0 specific decorators:

import "@cadl-lang/openapi3";

using OpenAPI;

// Using `using`
@useRef("common.json#/components/schemas/Foo")
model Foo {}

// Using fully qualified names
@OpenAPI.oneOf
union MyUnion {
  cat: Cat,
  dog: Dog,
}

Decorators

• @useRef
• @oneOf

@useRef

Syntax:

@useRef(urlString)

@useRef

@useRef is used to replace the Cadl model type in emitter output with a pre-existing named OpenAPI schema.

@oneOf

Syntax:

@oneOf()

@oneOfemits oneOf keyword for a union type in the resulting OpenAPI 3.0 specification. It indicates that the value of union type can only contain exactly one of the subschemas.

@oneOf can only be applied to a union types.

Emitter options:

Emitter options can be configured via the cadl-project.yaml configuration:

emitters:
  '@cadl-lang/openapi3':
    <optionName>: <value>


# For example
emitters:
  '@cadl-lang/openapi3':
    outputFile: my-custom-openapi.json

or via the command line with

--option "@cadl-lang/openapi3.<optionName>=<value>"

# For example
--option "@cadl-lang/openapi3.output-file=my-custom-openapi.json"

output-file

Configure the name of the swagger output file relative to the compiler output-path.

new-line

Set the newline character for emitting files. Can be either:

• lf(Default)
• crlf

omit-unreachable-types

Only include types referenced via an operation.

See also

• Cadl Getting Started
• Cadl Website
• Cadl for the OpenAPI Developer