@typespec/http-specs 0.37.2

package/specs/routes/main.tsp

@@ -0,0 +1,476 @@
+import "@typespec/http";
+import "@typespec/spec-lib";
+
+using TypeSpec.Http;
+
+/**
+ * Define scenario in building the http route/uri
+ */
+@scenarioService("/routes")
+namespace Routes;
+
+@scenario
+@scenarioDoc("""
+  Simple operation at a fixed in an interface
+    Expected path: /routes/fixed
+  """)
+@route("fixed")
+op fixed(): void;
+
+@scenario
+@scenarioDoc("""
+  Simple operation at a fixed in an interface
+    Expected path: /routes/in-interface/fixed
+  """)
+@route("in-interface")
+interface InInterface {
+  @route("fixed")
+  fixed(): void;
+}
+
+@route("path")
+namespace PathParameters {
+  @scenario
+  @scenarioDoc("""
+    Path parameter defined implicitly
+      Value: "a"
+      Expected path: /routes/path/template-only/a
+    """)
+  @route("template-only/{param}")
+  op templateOnly(param: string): void;
+
+  @scenario
+  @scenarioDoc("""
+    Path parameter defined explicitly
+      Value: "a"
+      Expected path: /routes/path/explicit/a
+    """)
+  @route("explicit/{param}")
+  op explicit(@path param: string): void;
+
+  @scenario
+  @scenarioDoc("""
+    Path parameter annotated with @path but not defined explicitly in the route
+      Value: "a"
+      Expected path: /routes/path/annotation-only/a
+    """)
+  @route("annotation-only")
+  op annotationOnly(@path param: string): void;
+
+  @route("reserved-expansion")
+  namespace ReservedExpansion {
+    @scenario
+    @scenarioDoc("""
+      Defines a path parameter that shouldn't encode reserved characters. It should however still encode the other url characters.
+        Param value: "foo/bar baz"
+        Expected path: "/routes/path/reserved-expansion/template/foo/bar%20baz"
+      """)
+    @route("template/{+param}")
+    op template(param: string): void;
+
+    @scenario
+    @scenarioDoc("""
+      Defines a path parameter that shouldn't encode reserved characters. It should however still encode the other url characters.
+        Param value: "foo/bar baz"
+        Expected path: "/routes/path/reserved-expansion/annotation/foo/bar%20baz"
+      """)
+    @route("annotation")
+    op annotation(@path(#{ allowReserved: true }) param: string): void;
+  }
+
+  @route("simple")
+  namespace SimpleExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/simple/standard/primitivea
+        """)
+      @route("primitive{param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/simple/standard/arraya,b
+        """)
+      @route("array{param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/simple/standard/recorda,1,b,2
+        """)
+      @route("record{param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/simple/explode/primitivea
+        """)
+      @route("primitive{param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/simple/explode/arraya.b
+        """)
+      @route("array{param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test simple expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/simple/explode/recorda=1,b=2
+        """)
+      @route("record{param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("path")
+  namespace PathExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/path/standard/primitive/a
+        """)
+      @route("primitive{/param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/path/standard/array/a,b
+        """)
+      @route("array{/param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/path/standard/record/a,1,b,2
+        """)
+      @route("record{/param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/path/explode/primitive/a
+        """)
+      @route("primitive{/param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/path/explode/array/a/b
+        """)
+      @route("array{/param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test path expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/path/explode/record/a=1/b=2
+        """)
+      @route("record{/param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("label")
+  namespace LabelExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/label/standard/primitive.a
+        """)
+      @route("primitive{.param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/label/standard/array.a,b
+        """)
+      @route("array{.param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/label/standard/record.a,1,b,2
+        """)
+      @route("record{.param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/label/explode/primitive.a
+        """)
+      @route("primitive{.param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/label/explode/array.a.b
+        """)
+      @route("array{.param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test label expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/label/explode/record.a=1.b=2
+        """)
+      @route("record{.param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("matrix")
+  namespace MatrixExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/matrix/standard/primitive;a
+        """)
+      @route("primitive{;param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/matrix/standard/array;a,b
+        """)
+      @route("array{;param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/matrix/standard/record;a,1,b,2
+        """)
+      @route("record{;param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/matrix/explode/primitive;a
+        """)
+      @route("primitive{;param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/matrix/explode/array;a.b
+        """)
+      @route("array{;param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test matrix expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/matrix/explode/record;a=1;b=2
+        """)
+      @route("record{;param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+}
+
+@route("query")
+namespace QueryParameters {
+  @scenario
+  @scenarioDoc("Query parameter defined implicitly")
+  @route("template-only{?param}")
+  op templateOnly(param: string): void;
+
+  @scenario
+  @scenarioDoc("Query parameter marked with explicit @query")
+  @route("explicit{?param}")
+  op explicit(@query param: string): void;
+
+  @scenario
+  @scenarioDoc("Query parameter annotated with @query but not defined explicitly in the route")
+  @route("annotation-only")
+  op annotationOnly(@query param: string): void;
+
+  @route("query-expansion")
+  namespace QueryExpansion {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-expansion/standard/primitive?param=a
+        """)
+      @route("primitive{?param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-expansion/standard/array?param=a,b
+        """)
+      @route("array{?param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-expansion/standard/record?param=a,1,b,2
+        """)
+      @route("record{?param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-expansion/explode/primitive?param=a
+        """)
+      @route("primitive{?param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-expansion/explode/array?param=a&param=b
+        """)
+      @route("array{?param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-expansion/explode/record?a=1&b=2
+        """)
+      @route("record{?param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+
+  @route("query-continuation")
+  namespace QueryContinuation {
+    @route("standard")
+    namespace Standard {
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: false when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-continuation/standard/primitive?fixed=true&param=a
+        """)
+      @route("primitive?fixed=true{&param}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: false when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-continuation/standard/array?fixed=true&param=a,b
+        """)
+      @route("array?fixed=true{&param}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: false when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-continuation/standard/record?fixed=true&param=a,1,b,2
+        """)
+      @route("record?fixed=true{&param}")
+      op record(param: Record<int32>): void;
+    }
+
+    @route("explode")
+    namespace Explode {
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: true when passed a primitive value.
+            Param value: "a"
+            Expected path: /routes/query/query-continuation/explode/primitive?fixed=true&param=a
+        """)
+      @route("primitive?fixed=true{&param*}")
+      op primitive(param: string): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: true when passed an array value.
+            Param value: ["a","b"]
+            Expected path: /routes/query/query-continuation/explode/array?fixed=true&param=a&param=b
+        """)
+      @route("array?fixed=true{&param*}")
+      op array(param: string[]): void;
+
+      @scenario
+      @scenarioDoc("""
+        Test query continuation expansion with explode: true when passed a record value.
+            Param value: {a: 1, b: 2}
+            Expected path: /routes/query/query-continuation/explode/record?fixed=true&a=1&b=2
+        """)
+      @route("record?fixed=true{&param*}")
+      op record(param: Record<int32>): void;
+    }
+  }
+}

package/specs/routes/mockapi.ts

@@ -0,0 +1,158 @@
+import { mockapi, passOnSuccess, ScenarioMockApi, ValidationError } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+function defineUri(uri: string) {
+  const url = new URL("http://example.com" + uri);
+  return passOnSuccess(
+    mockapi.get(url.pathname, (req) => {
+      for (const [key, value] of url.searchParams.entries()) {
+        req.expect.containsQueryParam(key, value);
+      }
+      for (const param of Object.keys(req.query)) {
+        if (!url.searchParams.has(param)) {
+          throw new ValidationError(
+            `Unexpected query parameter ${param}`,
+            undefined,
+            req.query[param],
+          );
+        }
+      }
+      return { status: 204 };
+    }),
+  );
+}
+
+Scenarios.Routes_InInterface = defineUri("/routes/fixed");
+Scenarios.Routes_fixed = defineUri("/routes/in-interface/fixed");
+
+Scenarios.Routes_PathParameters_templateOnly = defineUri("/routes/path/template-only/a");
+Scenarios.Routes_PathParameters_explicit = defineUri("/routes/path/explicit/a");
+Scenarios.Routes_PathParameters_annotationOnly = defineUri("/routes/path/annotation-only/a");
+
+Scenarios.Routes_PathParameters_ReservedExpansion_template = defineUri(
+  "/routes/path/reserved-expansion/template/foo/bar%20baz",
+);
+Scenarios.Routes_PathParameters_ReservedExpansion_annotation = defineUri(
+  "/routes/path/reserved-expansion/annotation/foo/bar%20baz",
+);
+
+Scenarios.Routes_PathParameters_SimpleExpansion_Standard_primitive = defineUri(
+  "/routes/simple/standard/primitivea",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Standard_array = defineUri(
+  "/routes/simple/standard/arraya,b",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Standard_record = defineUri(
+  "/routes/simple/standard/recorda,1,b,2",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Explode_primitive = defineUri(
+  "/routes/simple/standard/primitivea",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Explode_array = defineUri(
+  "/routes/simple/standard/arraya,b",
+);
+Scenarios.Routes_PathParameters_SimpleExpansion_Explode_record = defineUri(
+  "/routes/simple/standard/recorda=1,b=2",
+);
+
+Scenarios.Routes_PathParameters_PathExpansion_Standard_primitive = defineUri(
+  "/routes/path/standard/primitive/a",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Standard_array = defineUri(
+  "/routes/path/standard/array/a,b",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Standard_record = defineUri(
+  "/routes/path/standard/record/a,1,b,2",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Explode_primitive = defineUri(
+  "/routes/path/standard/primitive/a",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Explode_array = defineUri(
+  "/routes/path/standard/array/a/b",
+);
+Scenarios.Routes_PathParameters_PathExpansion_Explode_record = defineUri(
+  "/routes/path/standard/record/a=1/b=2",
+);
+
+Scenarios.Routes_PathParameters_LabelExpansion_Standard_primitive = defineUri(
+  "/routes/label/standard/primitive.a",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Standard_array = defineUri(
+  "/routes/label/standard/array.a,b",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Standard_record = defineUri(
+  "/routes/label/standard/record.a,1,b,2",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Explode_primitive = defineUri(
+  "/routes/label/standard/primitive.a",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Explode_array = defineUri(
+  "/routes/label/standard/array.a.b",
+);
+Scenarios.Routes_PathParameters_LabelExpansion_Explode_record = defineUri(
+  "/routes/label/standard/record.a=1.b=2",
+);
+
+Scenarios.Routes_PathParameters_MatrixExpansion_Standard_primitive = defineUri(
+  "/routes/matrix/standard/primitive;a",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Standard_array = defineUri(
+  "/routes/matrix/standard/array;a,b",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Standard_record = defineUri(
+  "/routes/matrix/standard/record;a,1,b,2",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Explode_primitive = defineUri(
+  "/routes/matrix/standard/primitive;a",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Explode_array = defineUri(
+  "/routes/matrix/standard/array;a;b",
+);
+Scenarios.Routes_PathParameters_MatrixExpansion_Explode_record = defineUri(
+  "/routes/matrix/standard/record;a=1;b=2",
+);
+
+Scenarios.Routes_QueryParameters_templateOnly = defineUri("/routes/query/template-only?param=a");
+Scenarios.Routes_QueryParameters_explicit = defineUri("/routes/query/explicit?param=a");
+Scenarios.Routes_QueryParameters_annotationOnly = defineUri(
+  "/routes/query/annotation-only?param=a",
+);
+
+Scenarios.Routes_QueryParameters_QueryExpansion_Standard_primitive = defineUri(
+  "/routes/query/query-expansion/standard/primitive?param=a",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Standard_array = defineUri(
+  "/routes/query/query-expansion/standard/array?param=a,b",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Standard_record = defineUri(
+  "/routes/query/query-expansion/standard/record?param=a,1,b,2",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Explode_primitive = defineUri(
+  "/routes/query/query-expansion/explode/primitive?param=a",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Explode_array = defineUri(
+  "/routes/query/query-expansion/explode/array?param=a&param=b",
+);
+Scenarios.Routes_QueryParameters_QueryExpansion_Explode_record = defineUri(
+  "/routes/query/query-expansion/explode/record?a=1&b=2",
+);
+
+Scenarios.Routes_QueryParameters_QueryContinuation_Standard_primitive = defineUri(
+  "/routes/query/query-continuation/standard/primitive?fixed=true&param=a",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Standard_array = defineUri(
+  "/routes/query/query-continuation/standard/array?fixed=true&param=a,b",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Standard_record = defineUri(
+  "/routes/query/query-continuation/standard/record?fixed=true&param=a,1,b,2",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Explode_primitive = defineUri(
+  "/routes/query/query-continuation/explode/primitive?fixed=true&param=a",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Explode_array = defineUri(
+  "/routes/query/query-continuation/explode/array?fixed=true&param=a&param=b",
+);
+Scenarios.Routes_QueryParameters_QueryContinuation_Explode_record = defineUri(
+  "/routes/query/query-continuation/explode/record?fixed=true&a=1&b=2",
+);

package/specs/scratch/.gitignore

@@ -0,0 +1,3 @@
+# This directory reserved for creating scratch *.tsp for testing/experimentation
+**/*
+!.gitignore

package/specs/serialization/encoded-name/json/main.tsp

@@ -0,0 +1,45 @@
+import "@typespec/http";
+import "@typespec/spec-lib";
+
+using TypeSpec.Http;
+
+@doc("Projection")
+@supportedBy("dpg")
+@scenarioService("/serialization/encoded-name/json")
+namespace Serialization.EncodedName.Json;
+
+@route("/property")
+namespace Property {
+  model JsonEncodedNameModel {
+    /** Pass in true */
+    @encodedName("application/json", "wireName")
+    defaultName: boolean;
+  }
+
+  @scenario
+  @scenarioDoc("""
+    Testing that you send the right JSON name on the wire.
+    Your generated SDK should generate JsonEncodedNameModel with one property `defaultName` with wire name `wireName`.
+    
+    Expected request body:
+    ```json
+    {"wireName": true}
+    ```
+    """)
+  @post
+  op send(@bodyRoot body: JsonEncodedNameModel): NoContentResponse;
+
+  @scenario
+  @scenarioDoc("""
+    Testing that you deserialize the right json name over the wire.
+    
+    Your generated SDK should generate JsonEncodedNameModel with one property `defaultName` with wire name `wireName`.
+    
+    Expected response body:
+    ```json
+    {"wireName": true}
+    ```
+    """)
+  @get
+  op get(): JsonEncodedNameModel;
+}