OpenAPI 2 and 3 have distinct summary and description fields, but we only have one @doc so there's no way to use both. When something takes a summary and description, we seem to use @doc as summary. And when it only takes a description we use @doc as description.

• Add competition for keywords
• Map kind: CompletionItemKind to cadl types which will give icons to the completition
  Function type:
  
  Interface type
  

Similar to base64 but has + serialized as - and / serialized as _
Meant to be safe to be used in urls

When passing tempalte args to a non templated type it show the error where the model is defined not used.

Repro

import "@cadl-lang/rest";

model Foo extends Cadl.Http.CreatedResponse<SearchIndex> {

}

C:\dev\azsdk\cadl-azure\core\packages\rest\lib\http.cadl:25:1 - error invalid-template-args: Can't pass template arguments to non-templated type

Need a way to define security for an API. Probably just be specific with Rest library

OpenAPI way: https://swagger.io/docs/specification/authentication/

Proposal https://gist.github.com/timotheeguerin/c16b075776f55a5643ac32311f96c72a

Some of our "samples" pre-date the compilation unit test harness we have now. And they're not really samples that someone would want to emulate, more like edge cases that we can't regress. One example is the 'recursive' sample. We should go through the samples and convert those that would be better as unit tests to unit tests.

• recursive.cadl #35

OpenAPI "format" contains open value, "pattern" is for regEx. "format":"UUID" ARE widely used in our rest spec.

One choice is to add @pattern and repoint @Format to "format". Thoughts?

https://swagger.io/docs/specification/data-models/data-types/

See https://dev.azure.com/azure-sdk/public/_build/results?buildId=1195424&view=logs&j=69944193-f126-526b-b021-abb6fb4b38ee&t=a525eb91-4a52-5fc4-de8c-4f229a13c8bb

Notice there are runs with only info messages printing "Found ." and runs with multiple warnings printing "Found 0 warnings."

cc @timotheeguerin

model A {
  optionalEnum?: OptionalEnum = OptionalEnum.foo;
}

enum OptionalEnum {
  foo = "foo",
  bar,
}

See PR for initial implementation and issues #128

When trying to standardize on operations for a service, you frequently want to have a overridable default behavior. Consider an interface:

interface Operations<Resource, Error> {
    create(name:str, @body properties: Resource): Resource | Error
}

...but you also have a preferred (standard) error contract model that you want people to use in the vast majority of cases. While you can now specialize the template:

model StandardError { ... };

interface OperationsWithStandardError<Resource> mixes Operations<Resource, StandardError> {
}

you start running into an explosion of specializations as soon as you have more than one template argument that you want to default (e.g. standard filter parameters for list operations, client driven pagination parameters etc.).

// Library has models for default + alternate schemes for pagination
model TopSkip {
    @query top?: int;
    @query skip?: int;
}

model SkipToken {
    @header skipToken?: str;
}

// My service definition
interface AzureOperations<Resource, Error=StandardError, ClientDrivenPagination=TopSkip, CorrelationIds=ClientRequestId> {
  ...
}

// My service uses skipToken headers rather than top/skip query parameters
interface MyServiceOperations<Resource> mixes AzureOperations<ClientDrivenPagination=SkipToken> {}

https://github.com/microsoft/cadl/blob/5068fc43935e331941024fdf47716fa8a3a027c7/README.md?plain=1#L96-L105

In order to get this sample to compile I had to remove the using and change @route to @path.

Once it compiled, the file generated did not contain a path.

{
  "openapi": "3.0.0",
  "info": {
    "title": "(title)",
    "version": "0000-00-00"
  },
  "tags": [],
  "paths": {},
  "components": {}
}

I can compile this with no problem, though they all point to the same path:

@route("/pets")
namespace Pets {
  @doc("Operation with no decorator at all")
  op read(@path petId: int32): Pet;

  @doc("Operation with path in the decorator")
  @get("{petId}") op read2(@path petId: int32): Pet;

  @doc("Operation with no path in the decorator")
  @get op read3(@path petId: int32): Pet;
}

And the Swagger emitter will just keep the last one:

  "paths": {
    "/pets/{petId}": {
      "get": {
        "operationId": "Pets_read3",
        "summary": "Operation with no path in the decorator",
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    }
  }

I believe CADL should be able to validate that we are defining several times the same operations on the same path.

Comment that caused the issue

/*
Issues: 
- 200 instead of 204 for delete
*/

This came up as part of #110

Currently, multiple path segments designated on a model is disallowed. Is there a need to allow multiple path segments for a key:

• For composite keys (i.e. when there are multiple keys, but no parent resource)
  • possible example: Compute VM Gallery
  • How do we express ordering in the path segments without a route string (for autoroute)?
• If there are alternate paths to accessing the resource
  • this is a common pattern for ODATA APIs

Additionally, should we separate '@key' from path segments, and should we allow multiple `@key' properties in a model

• This comes up in arrays of complex types. The 'id' of a particular instance may be made up of multiple properties (e.g. firstName, lastName)
  • should we allow this
  • Is there any important ordering in keys (last name, first name, for example) that we want to preserve?

Quotes around property names are allowed but looks bad if not needed.
Should do the same as prettier does with js/ts which is only keep quotes if it is needed(Without the quote it isn't a valid identifier. E.g. api-version)

Here's an API returning 404.

import "@cadl-lang/rest";
import "@cadl-lang/openapi3";

using Cadl.Http;

@route("/example")
namespace Example {
  op get(): { @header statusCode: 404; };
}

Here is the output. We describe this as "a successful response" even though it is not really. Should we have default descriptions based on the numeric range of the response code?

{
  "openapi": "3.0.0",
  "info": {
    "title": "(title)",
    "version": "0000-00-00"
  },
  "tags": [],
  "paths": {
    "/example/get": {
      "get": {
        "operationId": "Example_get",
        "parameters": [],
        "responses": {
          "404": {
            "description": "A successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "x-cadl-name": "(anonymous model)"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {}
}

When an enum has decorator it removes new lines between entries which makes it look very busy and harder to read.

@doc("Defines the data type of a field in a search index.")
enum SearchFieldDataType {
  @doc("Indicates that a field contains a string.")
  String: "Edm.String",
  @doc("Indicates that a field contains a 32-bit signed integer.")
  Int32: "Edm.Int32",
  @doc("Indicates that a field contains a 64-bit signed integer.")
  Int64: "Edm.Int64",
  @doc("Indicates that a field contains an IEEE double-precision floating point number.")
  Double: "Edm.Double",
  @doc("Indicates that a field contains a Boolean value (true or false).")
  Boolean: "Edm.Boolean",
  @doc("Indicates that a field contains a date/time value, including timezone information.")
  DateTimeOffset: "Edm.DateTimeOffset",
  @doc("Indicates that a field contains a geo-location in terms of longitude and latitude.")
  GeographyPoint: "Edm.GeographyPoint",
  @doc("Indicates that a field contains one or more complex objects that in turn have sub-fields of other types.")
  ComplexType: "Edm.ComplexType",
}

Should either:

• Use the same logic as model members(Put space betweeen decorator and above property)
• Use same logic as namespace. Keep at least one new line if the user placed one.

Makes more sense to go for 1. IMO

Certain things in Cadl libraries exist to help the Cadl developer write a spec and their documentation should be shown in the IDE, but should not bleed through emitters to the end user. One example is #126 and I believe the various resource operation mixin interfaces are like this too.

We need a way to distinguish these docs from @doc. We could make a different decorator or use a jsdoc style for instead for these.

EDIT Proposal: https://gist.github.com/nguerrera/01158db039e103dd37201c66978ce10b

One format autorest supported for string schemas was duration.
We have plainTime, plainDate and zonedDatetime but lacking model to represent duration.

One of the schemas in the body-complex sample is using it.

model Foo {
  // Some comment
} 

gets formatted to

model Foo {
  // Some comment
} 

probably needs to check before formatting model to be empty if it contains a comment

Extracted from https://github.com/Azure/cadl-azure/issues/886

Scenarios to think about:

Current proposal https://gist.github.com/timotheeguerin/39ba871ab9d13832cc6227e680df2096

Current having a response like

model Response {
  @contentType: "application/octet-stream";
  @body body: bytes;
}

Should produce

content: 
  application/octect-stream:
    schema: 
       type: "string"
       format: "binary"

fix in:

• openapi3 #125
• cadl-autorest https://github.com/Azure/cadl-azure/pull/1065

Compile this:

import "@cadl-lang/openapi3";
import "@cadl-lang/rest";

using Cadl.Http;

model ErrorTemplate<T> {
  @doc("Error code.") code: T;
  innererror?: InnerError;
}

model Error is ErrorTemplate<ErrorCode> {}
model InnerError is ErrorTemplate<InnerErrorCode> {}

enum ErrorCode {
  A,
  B,
  C
}

enum InnerErrorCode {
  C,
  D,
  E
}

@route("/")
namespace N {
  op M(): Error;
}

Get this:

TypeError: Cannot set properties of undefined (setting 'description')
    at getSchemaForModel (file:///C:/Temp/aqe/node_modules/@cadl-lang/openapi3/dist/src/openapi.js:811:58)
    at getSchemaForType (file:///C:/Temp/aqe/node_modules/@cadl-lang/openapi3/dist/src/openapi.js:661:20)
    at emitReferences (file:///C:/Temp/aqe/node_modules/@cadl-lang/openapi3/dist/src/openapi.js:625:35)
    at Object.emitOpenAPI (file:///C:/Temp/aqe/node_modules/@cadl-lang/openapi3/dist/src/openapi.js:157:13)
    at $onBuild (file:///C:/Temp/aqe/node_modules/@cadl-lang/openapi3/dist/src/openapi.js:11:19)
    at createProgram (file:///C:/Temp/aqe/node_modules/@cadl-lang/compiler/dist/core/program.js:60:19)
    at async compile (file:///C:/Temp/aqe/node_modules/@cadl-lang/compiler/dist/core/program.js:475:12)
    at async Object.handler (file:///C:/Temp/aqe/node_modules/@cadl-lang/compiler/dist/core/cli.js:67:25)

If you remove the `@doc("Error code") comment, it doesn't crash, but still gives this:

main.cadl:6:21 - error @cadl-lang/openapi3/invalid-schema: Couldn't get schema for type TemplateParameter

The behavior in both cases is the same for cadl-autorest as cadl-lang/openapi3 so we should fix both.

Follow-on work for PR #89.

• Add a sample that uses discriminators as part of the samples converted to swagger on check-in
• Add documentation for discriminator in the language walkthrough

Consider this:

using A;
using B;

namespace A {
  model M {} // error here
}

namespace B {
  model M {} // and here
}

model Foo {
  m: M; 
}

C:\t\main.cadl:5:3 - error duplicate-symbol: Duplicate name: "M"
C:\t\main.cadl:9:3 - error duplicate-symbol: Duplicate name: "M"

This is misleading because M is not "duplicated" until you use both namespaces. It also means you can't have using A and using B together even when you never reference the colliding names or always fully qualify them.

Now look at morally equivalent C#, where I would argue the experience is much better. I think we should make things work this way.

using A;
using B;

namespace A {
  class M {}
}

namespace B {
  class M {}
}

class Foo {
  M m; // error here
}

C:\t\Program.cs(13,3,13,4): error CS0104: 'M' is an ambiguous reference between 'A.M' and 'B.M'

I should be able to declare a special string like

@doc("super special!")
@format("^x\w+x$")
model specialString is string;

and use this in place of string everywhere and see documentation and constraints reflected in the output openapi.

Rich text formatting in descriptions/documentation

Documentation for APIs often involve more than just raw text. Common reasons to use rich text formatting include rendering of tables or embedding links into the generated reference documentation.

For an example, see the APIM List By Tags endpoint which illustrates the attempt to use (valid) openapi descriptions that contains a table in the API documentation as well as the issue with tools treating description fields as plain text (broken rendering).

OpenAPI support for rich text

OpenAPI allows for rich text formatting in description fields using CommonMark. As evident from the example above, there are gaps in our toolset with regards to how rich text is handled.

Possible solution

• Only support CommonMark for input.
• Add new @richDoc decorator for rich documentation that takes a format parameter. The only supported value (for now) is CommonMark.

@richDoc(
"""
|One|Two|
|-|-|
|1|2|
|3|4|
""", "CommonMark")
model ModelWithTableDocs {};

Alternate solution

Change the @doc decorator so that it accepts CommonMark instead of raw text. For the most part, that is an extension to its current decorator definition (in most cases, you don't have accidental markup in the raw text), but it adds complexity to emitters since they have to sniff the format/convert to something they can manage or risk broken rendering as shown above.

Challenges/questions:

• There are many rich language definitions *in adition to CommonMark), as well as different dialects within a dialect. Is it enough to support just CommonMark?
• Client and service library code emitters want to emit descriptions as docstring/comments in generated code. Some langauges (e.g. Python) have idiomatic formats for rich text (in the case of Python, reStructuredText) but most languages expect plain text in their descriptions. Do we expect multiple formats in the specification or do we provide converters?

In this PR #157 I broke cadl compile . multiple times(with different issues) without any tests catching it. I think this is due to all our tests using the local linked library. The result of this can be quite bad as we'd release a completely unusable version of the compiler without noticing.

Proposal:

1. Package all the packages.
2. Install @cadl-lang/compiler package as global
3. Test 1:
   • Run cadl compile . on basic main.cadl referencing latest published version of compiler and libraries
   • Run cadl compile . on basic main.cadl referencing the packaged version from step 1.

The vscode library that tokenizes using textmate grammar can be used programatically.

Look at https://github.com/Azure/bicep/tree/main/src/textmate/test for inspiration.

https://github.com/Azure/azure-rest-api-specs/blob/dc439efcfc15448824877603f66fc1578d1c71c5/specification/search/data-plane/Microsoft.Azure.Search.Service/stable/2019-05-06/searchservice.json#L11

As soon as you have any headers, even the pseudo-header for the status code, the response model becomes a schema for content in the body. If the response model has only headers, there should be no content.

The only way I can find to have no content on the response is to have no properties at all in the response model.

@route("/repro")
namespace Repro {
  op create(@body body: string): {};
}

This generates:

{
 "paths": {
    "/repro": {
      "post": {
        "operationId": "Repro_create",
        "parameters": [],
        "responses": {
          "204": {
            "description": "No content"
          }
        }
      }
    }
  }

But then change it to this:

@route("/repro")
namespace Repro {
  op create(): AcceptedResponse;
}

And get this:

{
  "paths": {
    "/repro": {
      "post": {
        "operationId": "Repro_create",
        "parameters": [],
        "responses": {
          "202": {
            "description": "The request has been received but not yet acted upon.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cadl.Http.AcceptedResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Cadl.Http.AcceptedResponse": {
        "type": "object",
        "properties": {},
        "description": "The request has been received but not yet acted upon."
      }
    }
  }
}

AcceptedResponse is defined as follows.

model AcceptedResponse {
  @header statusCode: 202;
}

The problem seems to be around here:

https://github.com/microsoft/cadl/blob/34ff2a96445a8f60314799938d223c53e3db3bde/packages/openapi3/src/openapi.ts#L462-L465

We need to ignore header properties (including pseudo-header for status code) when deciding that there's no body. And then we need to make sure to keep the explicit status code if any and not overwrite it with 204 as we would if this part of the code were ignoring headers. Also, looking at the code, I don't think it's right to require the response model to have no base type to have no body. I think we should look at all the properties including inherited properties and see if there are only headers. It's weird to me if if model R extends EmptyOrHeadersOnly {} and model R {...ModelWithOnlyHeaders} /model R is ModelWithOnlyHeaders were different in this respect.

This issue is unique to the OpenAPI 3. We should compare the code with cadl-autorest and if we make any refinements beyond what cadl-autorest currently does, we should align cadl-autorest with those refinements.

import "@cadl-lang/rest";
import "@cadl-lang/openapi3";

using Cadl.Rest;
using Cadl.Rest.Resource;

interface Pets mixes ResourceOperations<Pet, {}> {}

model Pet {
  @segment("stores")
  @key
  storeId: int64;

  @segment("pets")
  @key
  id: int64;
}

Unhandled promise rejection!
Internal compiler error!
File issue at https://github.com/microsoft/cadl

Error: More than one key found on model type Pet
    at file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/rest/dist/resource.js:41:23
    at Map.forEach (<anonymous>)
    at getResourceTypeKey (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/rest/dist/resource.js:38:29)
    at cloneKeyProperties (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/rest/dist/resource.js:67:25)
    at $copyResourceKeyParameters (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/rest/dist/resource.js:108:9)
    at applyDecoratorToType (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/compiler/dist/core/checker.js:1268:13)
    at createType (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/compiler/dist/core/checker.js:1257:17)
    at checkModelStatement (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/compiler/dist/core/checker.js:819:13)
    at checkModel (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/compiler/dist/core/checker.js:762:20)
    at getTypeForNode (file:///C:/dev/azsdk/cadl-dogfood/node_modules/@cadl-lang/compiler/dist/core/checker.js:147:24)

not exactly sure if that's supposed to not be allowed but either way it shouldn't crash

When defining an interface with a template parameter it cause an error

interface Adoptable<TResource> {
  @Cadl.Http.post adpot(
    ...ResourceParameters<TResource>
  ): TResource | PetStoreError;
}
interface Dogs mixes ResourceOperations<Dog, PetStoreError>, Adoptable<Dog> {}
interface Cats mixes ResourceOperations<Cat, PetStoreError>, Adoptable<Cat> {}

model Cat {}
model Dog {}

error:

C:\dev\azsdk\cadl-dogfood\main.cadl:25:23 - error @cadl-lang/openapi3/invalid-schema: Couldn't get schema for type TemplateParameter

This eror doesn't happen if Adoptable is moved to another file and imported

Solution might just be making sure the emitter doesn't pull template interfaces

Including using Cadl; in the spec cause an aggregate error

AggregateError: Multiple errors. See errors array.
    at computeTargetLocation (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:73:15)
    at logDiagnostics (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:83:29)
    at onCompileFinished (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/cli.js:152:13)
    at async Object.handler (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/cli.js:67:25) {
  errors: [
    Error: Error(s) occurred trying to resolve target: [object Object]
        at computeTargetLocation (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:72:33)
        at logDiagnostics (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:83:29)
        at onCompileFinished (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/cli.js:152:13)
        at async Object.handler (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/cli.js:67:25),
    AssertionError [ERR_ASSERTION]: Cannot obtain source file of unbound node.
        at new AssertionError (internal/assert/assertion_error.js:456:5)
        at compilerAssert (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:221:19)
        at getSourceLocationOfNode (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:149:5)
        at getSourceLocation (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:135:12)
        at computeTargetLocation (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:64:24)
        at logDiagnostics (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/diagnostics.js:83:29)
        at onCompileFinished (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/cli.js:152:13)
        at async Object.handler (file:///C:/dev/azsdk/cadl/packages/compiler/dist/core/cli.js:67:25) {
      generatedMessage: false,
      code: 'ERR_ASSERTION',
      actual: undefined,
      expected: undefined,
      operator: undefined
    }
  ]
}

List of things that could be formatted better:

1. Decorator with a single value being very long could be formatted in a single line instead of splitting

@doc("with a very long comment ......")

formats to

@doc(
  "with a very long comment ......"
)

2. Mixes too long line

interface DocumentModels mixes ResourceOperations<ModelSummary, ErrorResponse>, ResourceOperations<ModelSummary, ErrorResponse>, ResourceOperations<ModelSummary, ErrorResponse>, ResourceOperations<ModelSummary, ErrorResponse> {}

Try to format to this?

interface DocumentModels mixes 
    ResourceOperations<ModelSummary, ErrorResponse>, 
    ResourceOperations<ModelSummary, ErrorResponse>, 
    ResourceOperations<ModelSummary, ErrorResponse>, 
    ResourceOperations<ModelSummary, ErrorResponse> {
          
}

3. Interface should keep empty lines between operation

Like namespaces it shouldn't concat all operation together but preserve an empty line if there is 1+ between operation

model Foo {
  @doc("foo" | "bar")
  test: string;
}

This happened when using wanting to use quotes but forgetting to escape and it happens to produce a valid Cadl syntax.

Error:

TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    |     property 'options' -> object with constructor 'Array'
    |     index 0 -> object with constructor 'Object'
    --- property 'parent' closes the circle
    at JSON.stringify (<anonymous>)
    at Object.emitOpenAPI (file:///C:/dev/azsdk/cadl-azure/packages/cadl-autorest/dist/src/openapi.js:172:100)
    at $onBuild (file:///C:/dev/azsdk/cadl-azure/packages/cadl-autorest/dist/src/openapi.js:13:19)
    at async createProgram (file:///C:/dev/azsdk/cadl-azure/core/packages/compiler/dist/core/program.js:60:13)
    at async compile (file:///C:/dev/azsdk/cadl-azure/core/packages/compiler/dist/core/program.js:479:12)
    at async Object.handler (file:///C:/dev/azsdk/cadl-azure/core/packages/compiler/dist/core/cli.js:67:25)

The problem with @doc specifically might just be to verify the value passed is a string and nothing else.

At the time of bug bash early Dec 2021:
https://github.com/microsoft/cadl/blob/main/docs/cadl-for-openapi-dev.md#path-item-object

@resource("/pets")
namespace Pets {
  op @get list(): Pet[];                  // get on path "/pets"
  op @get read(@path petId: int32): Pet;  // get on path "/pets/{petId}"
  @post("{petId}:walk")
  op walk(... PetId): {};                 // post on path "/pets/{petId}:walk"
}

is incorrect

Language server seems to crash when there is aggregate error. Error example: #93

These all stack overflow and should issue an error diagnostic instead:

model A is A {}
model A extends A {}
model A is B {}; model B is A {}
model A extends B {}; model B extends A {}

For example, the identifier of operations in an interface should be colored like the id of an operation or other declaration, but is presently uncolored.

The union statement was introduced to support "named unions" (a la Rust and Swift). But we also allow union to define regular "unnamed" unions by simply omitting the variant names, e.g.:

union Pet { Cat, Dog }

The compiler currently complains about this syntax:

error token-expected: ':' expected.

• defaults
• Packages specifics:
  • openapi3
  • rest

Single quotes are not valid in Cadl but they are not flagged in the VSCode extension.

Simple recreate:

import "@cadl-lang/rest";
import "@cadl-lang/openapi3";

using Cadl.Http;

model Pet {
  name: string;
}

model CreatedResponse {
  @statusCode code: '201';
}

@route("/Pets")
namespace Pets {
  op create(): CreatedResponse & Pet;
}

This fails to compile with:

Diagnostics were reported during compilation:

/Users/mikekistler/Projects/Microsoft/cadl/packages/samples/scratch/bug.cadl:11:21 - error invalid-character: Invalid character.
/Users/mikekistler/Projects/Microsoft/cadl/packages/samples/scratch/bug.cadl:11:21 - error token-expected: Expression expected.
/Users/mikekistler/Projects/Microsoft/cadl/packages/samples/scratch/bug.cadl:11:25 - error invalid-character: Invalid character.
/Users/mikekistler/Projects/Microsoft/cadl/packages/samples/scratch/bug.cadl:11:22 - error token-expected: Statement expected.
/Users/mikekistler/Projects/Microsoft/cadl/packages/samples/scratch/bug.cadl:12:1 - error token-expected: Statement expected.

But no warnings are shown in VSCode.

The code compiles cleanly when the single quotes are changed to double quotes.

Today you have to specify a path to a cadl-server(.cmd) executable. This is hard for two reasons:

1. Even if you have that, it's deep and hard to find
2. If you want to run against a local build of the package, as we do, you don't even have that.

Our workaround for (2) to use the .bin/cadl-server in packages/samples that consumes packages/compiler.

It would be better if you could just specify the package path and it worked.

• Add a decorator and detection function to designate models as errors when included in an operation response. Per this design issue
• OpenAPI emitters use @error, when present to determine default responses.

Specially as we used to support @get(<uri>) there is some specs that still have that and are causing issues

Occurs only if the comment has no new line after it.

/**
 *
 */<EOF>

Should have some base instructions around building, running tests, and creating PRs for OSS contributors.

Compile this:

import "@cadl-lang/openapi3";
import "@cadl-lang/rest";

using Cadl.Http;

model ErrorBase {
  innererror: InnerError;
}

model Error is ErrorBase {
  code: ErrorCode; 
}

model InnerError is ErrorBase {
  code: InnerErrorCode; 
}

enum ErrorCode {
  A,
  B,
  C
}

enum InnerErrorCode {
  C,
  D,
  E
}

@route("/")
namespace N {
  op M(): Error;
}

Get this:

{
  "schemas": {
    "Error": {
      "type": "object",
      "properties": {
        "innererror": {
          "$ref": "#/components/schemas/InnerError"
        },
        "code": {
          "$ref": "#/components/schemas/ErrorCode"
        }
      },
      "required": [
        "innererror",
        "code"
      ]
    },
    "InnerError": {
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/components/schemas/InnerErrorCode"
        }
      },
      "required": [
        "code"
      ]
    },
    "ErrorCode": {
      "type": "string",
      "enum": [
        "A",
        "B",
        "C"
      ]
    },
    "InnerErrorCode": {
      "type": "string",
      "enum": [
        "C",
        "D",
        "E"
      ]
    }
  }
}

Notice that InnerError model is missing the innererror property. The same thing happens with cadl-autorest. This might be an issue in the compiler and not the emitter and it might be related to #133