Neutrino Packing Machine

    @azure-tools/cadl-autorest
    TypeScript icon, indicating that this package has built-in type declarations

    0.20.0 • Public • Published

    Cadl AutoRest Library

    This is a Cadl library that will emit an enriched OpenAPI 2.0 specification that can be consumed by AutoRest. The generated OpenAPI spec will have custom x-ms- extensions properties and conform to standards required by AutoRest to generate a more accurate SDK.

    Getting started

    1. Include @azure-tools/cadl-autorest dependencies in package.json
    {
      ...
      "dependencies": {
        ...
        "@azure-tools/cadl-autorest": "latest"
      }
    }
    1. Run npm install to install the dependency
    2. Import @azure-tools/cadl-autorest in your main.cadl file
    import "@azure-tools/cadl-autorest";
    
    1. Run cadl compile. This will result in a swagger.json file crated in ./cadl-output/swagger.json

    Use in autorest

    Manually

    Generate the OpenAPI spec as shown above then run autorest cli directly on it.

    Via Autorest

    AutoRest provides a plugin that will directly take Cadl as input. Make sure to use Autorest Core >=3.6.0

    autorest --cadl --input-file=./main.cadl

    Configuration

    Output path

    Specify the --output-path option, this changes the directory where the OpenAPI specification (openapi.json) wil be omitted:

    cadl compile --output-path=`./custom`

    Emitter options:

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

    emitters:
      '@azure-tools/cadl-autorest':
        <optionName>: <value>
    
    
    # For example
    emitters:
      '@azure-tools/cadl-autorest':
        output-file: my-custom-swagger.json

    or via the command line with

    --option "@azure-tools/cadl-autorest.<optionName>=<value>"
    
    # For example
    --option "@azure-tools/cadl-autorest.output-file=my-custom-swagger.json"

    output-file

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

    examples-directory

    Directory where the x-ms-examples are located so the emitter can automatically link.

    version

    Select which version should be emitted if the spec support versioning. By default all the version with be emitted in this format <outputFileName>.<version>.json

    new-line

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

    • lf(Default)
    • crlf

    Decorators

    @asyncOperationOptions

    Syntax:

    @asyncOperationOptions(finalStateVia)
    

    @asyncOperationOptions allows specify swagger extension x-ms-long-running-operation-options's finalStateVia option.

    @asyncOperationOptions can only be specified on operations.

    @collectionFormat

    Syntax:

    @collectionFormat(formatString)
    

    @collectionFormat specifies array property type serialization format. Valid format strings are "csv", "multi", "ssv", "tsv", "pipes" though "csv" or "multi" are recommended.

    @collectionFormat can only be specified on model properties that are arrays.

    @example

    Syntax:

    @example(pathOrUri, title)
    

    @example attaches example files to an operation. Multiple examples can be specified.

    @example can only be specified on operations.

    @useRef

    Syntax:

    @useRef(urlString)
    

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

    Keywords

    Install

    npm i @azure-tools/cadl-autorest

    DownloadsWeekly Downloads

    2,058

    Version

    0.20.0

    License

    MIT

    Unpacked Size

    176 kB

    Total Files

    31

    Last publish

    Collaborators

    • azure-sdk