kristapratico / cadl-dogfood

Boilerplate for a cadl repo for user to quickly get started

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Cadl Dogfood repo

This is a repo containing a basic REST API project to get started with CADL.

See notes for known issues and things to watch for

Prerequisites

[Required] Cadl cli/compiler

Option 1: Via Node

  1. Install node 14.x or node 16.x. CADL is NOT compatible with version of node below 14.x
  2. Install package globally
npm install -g @cadl-lang/compiler

Option 2: Via docker

See docs for full docker documentations.

  1. Install docker
  2. For all the following steps replace the cadl ecutable from the command with the following line
docker run -v "${pwd}:/wd" --workdir="/wd"  -t azsdkengsys.azurecr.io/cadl

[Recommended] VSCode and extensions

Install the following extensions:

  • prettier: Provide auto formatting for cadl language
  • cadl: cadl extension, will provide error reporting and syntax highlighting for cadl files. To install that extension run
cadl code install

Visual studio

NOTE: For Visual Studio, you must open the folder from the command-line (devenv . from the Cadl project folder) to inherit the proper environment.

Getting started

  1. Install cadl libraries for this project
cadl install
  1. Compile
cadl compile .
  1. Produced openapi.json in ./cadl-output folder

  2. Dev with --watch to rebuild on changes (Not working when using docker.)

cadl compile . --watch
  1. Edit main.cadl. Hello world sample is laying there

  2. Optional (Needs docker): Run swagger ui on output openapi => ./swager-ui.sh(Linux/MacOS) or ./swagger-ui.ps1 (Windows)

Command summary

Action Command
Help cadl --help
Compile once cadl compile .
Compile in watch mode cadl compile . --watch
Format cadl code cadl format **/*.cadl
Install dependencies cadl install
Install dependencies cadl install
Install VSCode extension cadl code install
Init a new project cadl init [tempalateUrl]

Notes

  1. When defining operations under a namespace the @route decorator is required on the namespace or it won't be discovered and emitted.
  2. You cannot define operations at the root of the file
  3. Issue with generic interface interface Adoptable<TPet, TError> {} that cannot be defined in the main file. Workaround is to define the generic interface in another file and import it. import "./foo.cadl"
  4. Do not remove the import "@cadl-lang/openapi3" import as this is what register the openapi emitter (Specially if copying one of the samples). Without it nothing gets emitted.

About

Boilerplate for a cadl repo for user to quickly get started

License:MIT License


Languages

Language:PowerShell 50.0%Language:Shell 50.0%