@typespec/http-specs 0.1.0-alpha.0

package/specs/type/union/main.tsp

@@ -0,0 +1,249 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+/**
+ * Describe scenarios for various combinations of unions.
+ */
+@scenarioService("/type/union")
+namespace Type.Union;
+
+model Cat {
+  name: string;
+}
+
+model Dog {
+  bark: string;
+}
+
+enum LR {
+  left,
+  right,
+}
+enum UD {
+  up,
+  down,
+}
+
+/**
+ * Describe union of string "a" | "b" | "c"
+ */
+@route("/strings-only")
+interface StringsOnly extends GetAndSend<"a" | "b" | "c", "\"b\""> {}
+
+/**
+ * Describe union of string string | "b" | "c"
+ */
+@route("/string-extensible")
+interface StringExtensible extends GetAndSend<string | "b" | "c", "\"custom\""> {}
+
+union StringExtensibleNamedUnion {
+  string,
+  OptionB: "b",
+  "c",
+}
+/**
+ * Describe union of string string | "b" | "c" but where the union is named and some of the variants are named
+ */
+@route("/string-extensible-named")
+interface StringExtensibleNamed extends GetAndSend<StringExtensibleNamedUnion, "\"custom\""> {}
+
+/**
+ * Describe union of integer 1 | 2 | 3
+ */
+@route("/ints-only")
+interface IntsOnly extends GetAndSend<1 | 2 | 3, "2"> {}
+
+/**
+ * Describe union of floats 1.1 | 2.2 | 3.3
+ */
+@route("/floats-only")
+interface FloatsOnly extends GetAndSend<1.1 | 2.2 | 3.3, "2.2"> {}
+
+/**
+ * Describe union of models
+ */
+@route("/models-only")
+interface ModelsOnly
+  extends GetAndSend<
+      Cat | Dog,
+      """
+        {
+          "name": "test"
+        }
+        """
+    > {}
+
+model EnumsOnlyCases {
+  /** This should be receive/send the left variant */
+  lr: LR | UD;
+
+  /** This should be receive/send the up variant */
+  ud: UD | UD;
+}
+
+/**
+ * Describe union of 2 different enums
+ */
+@route("/enums-only")
+interface EnumsOnly
+  extends GetAndSend<
+      LR | UD,
+      """
+        {
+          "lr": "right",
+          "ud": "up"
+        }
+        """,
+      EnumsOnlyCases
+    > {}
+
+model StringAndArrayCases {
+  /** This should be receive/send the string variant */
+  string: string | string[];
+
+  /** This should be receive/send the array variant */
+  array: string | string[];
+}
+
+/**
+ * Describe union of a string and an array of strings
+ */
+@route("/string-and-array")
+interface StringAndArray
+  extends GetAndSend<
+      string | string[],
+      """
+        {
+          "string": "test",
+          "array": ["test1", "test2"]
+        }
+        """,
+      StringAndArrayCases
+    > {}
+
+alias MixedLiteralsUnion = "a" | 2 | 3.3 | true;
+model MixedLiteralsCases {
+  /** This should be receive/send the "a" variant */
+  stringLiteral: MixedLiteralsUnion;
+
+  /** This should be receive/send the 2 variant */
+  intLiteral: MixedLiteralsUnion;
+
+  /** This should be receive/send the 3.3 variant */
+  floatLiteral: MixedLiteralsUnion;
+
+  /** This should be receive/send the true variant */
+  booleanLiteral: MixedLiteralsUnion;
+}
+
+/**
+ * Describe union of floats "a" | 2 | 3.3
+ */
+@route("/mixed-literals")
+interface MixedLiterals
+  extends GetAndSend<
+      MixedLiteralsUnion,
+      """
+        {
+          "stringLiteral": "a",
+          "intLiteral": 2,
+          "floatLiteral": 3.3,
+          "booleanLiteral": true
+        }
+        """,
+      MixedLiteralsCases
+    > {}
+
+alias MixedTypesUnion = Cat | "a" | int32 | boolean;
+model MixedTypesCases {
+  /** This should be receive/send the Cat variant */
+  `model`: MixedTypesUnion;
+
+  /** This should be receive/send the "a" variant */
+  literal: MixedTypesUnion;
+
+  /** This should be receive/send the int variant */
+  int: MixedTypesUnion;
+
+  /** This should be receive/send the boolean variant */
+  boolean: MixedTypesUnion;
+
+  /** This should be receive/send 4 element with Cat, "a", int, and boolean */
+  array: MixedTypesUnion[];
+}
+
+/**
+ * Describe union of floats "a" | 2 | 3.3
+ */
+@route("/mixed-types")
+interface MixedTypes
+  extends GetAndSend<
+      MixedTypesUnion,
+      """
+        {
+          "model": {
+            "name": "test"
+          },
+          "literal": "a",
+          "int": 2,
+          "boolean": true,
+          "array": [
+            {
+              "name": "test"
+            },
+            "a",
+            2,
+            true
+          ]
+        }
+        """,
+      MixedTypesCases
+    > {}
+
+/**
+ * Helper interface to describe a test involving getting and sending a specific data
+ */
+interface GetAndSend<Union, Payload extends valueof string, Cases = Union> {
+  @scenario
+  @scenarioDoc(
+    """
+      Verify a union can be processed in a response: 
+      ```tsp
+      {type}
+      ```
+      
+      Expected response body:
+      ```json
+      { "prop": ${Payload}}
+      ```
+      """,
+    {
+      type: Union,
+    }
+  )
+  get(): {
+    prop: Cases;
+  };
+
+  @scenario
+  @scenarioDoc(
+    """
+      Verify a union can be processed in a response: 
+      ```tsp
+      {type}
+      ```
+      
+      Expected request to send body:
+      ```json
+      { "prop": ${Payload}}
+      ```
+      """,
+    {
+      type: Union,
+    }
+  )
+  send(prop: Cases): void;
+}

package/specs/type/union/mockapi.ts

@@ -0,0 +1,130 @@
+import { json, passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+function createGetServerTests(url: string, value: unknown) {
+  return passOnSuccess({
+    uri: url,
+    method: `get`,
+    request: {},
+    response: {
+      status: 200,
+      body: json({ prop: value }),
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+function createPostServerTests(url: string, value: unknown) {
+  return passOnSuccess({
+    uri: url,
+    method: `post`,
+    request: {
+      body: {
+        prop: value,
+      },
+    },
+    response: {
+      status: 204,
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+Scenarios.Type_Union_StringsOnly_get = createGetServerTests(`/type/union/strings-only`, "b");
+Scenarios.Type_Union_StringsOnly_send = createPostServerTests(`/type/union/strings-only`, "b");
+
+Scenarios.Type_Union_StringExtensible_get = createGetServerTests(
+  `/type/union/string-extensible`,
+  "custom",
+);
+Scenarios.Type_Union_StringExtensible_send = createPostServerTests(
+  `/type/union/string-extensible`,
+  "custom",
+);
+
+Scenarios.Type_Union_StringExtensibleNamed_get = createGetServerTests(
+  `/type/union/string-extensible-named`,
+  "custom",
+);
+Scenarios.Type_Union_StringExtensibleNamed_send = createPostServerTests(
+  `/type/union/string-extensible-named`,
+  "custom",
+);
+
+Scenarios.Type_Union_IntsOnly_get = createGetServerTests(`/type/union/ints-only`, 2);
+Scenarios.Type_Union_IntsOnly_send = createPostServerTests(`/type/union/ints-only`, 2);
+
+Scenarios.Type_Union_FloatsOnly_get = createGetServerTests(`/type/union/floats-only`, 2.2);
+Scenarios.Type_Union_FloatsOnly_send = createPostServerTests(`/type/union/floats-only`, 2.2);
+
+Scenarios.Type_Union_ModelsOnly_get = createGetServerTests(`/type/union/models-only`, {
+  name: "test",
+});
+Scenarios.Type_Union_ModelsOnly_send = createPostServerTests(`/type/union/models-only`, {
+  name: "test",
+});
+
+Scenarios.Type_Union_EnumsOnly_get = createGetServerTests(`/type/union/enums-only`, {
+  lr: "right",
+  ud: "up",
+});
+Scenarios.Type_Union_EnumsOnly_send = createPostServerTests(`/type/union/enums-only`, {
+  lr: "right",
+  ud: "up",
+});
+
+Scenarios.Type_Union_StringAndArray_get = createGetServerTests(`/type/union/string-and-array`, {
+  string: "test",
+  array: ["test1", "test2"],
+});
+Scenarios.Type_Union_StringAndArray_send = createPostServerTests(`/type/union/string-and-array`, {
+  string: "test",
+  array: ["test1", "test2"],
+});
+
+Scenarios.Type_Union_MixedLiterals_get = createGetServerTests(`/type/union/mixed-literals`, {
+  stringLiteral: "a",
+  intLiteral: 2,
+  floatLiteral: 3.3,
+  booleanLiteral: true,
+});
+Scenarios.Type_Union_MixedLiterals_send = createPostServerTests(`/type/union/mixed-literals`, {
+  stringLiteral: "a",
+  intLiteral: 2,
+  floatLiteral: 3.3,
+  booleanLiteral: true,
+});
+
+Scenarios.Type_Union_MixedTypes_get = createGetServerTests(`/type/union/mixed-types`, {
+  model: {
+    name: "test",
+  },
+  literal: "a",
+  int: 2,
+  boolean: true,
+  array: [
+    {
+      name: "test",
+    },
+    "a",
+    2,
+    true,
+  ],
+});
+Scenarios.Type_Union_MixedTypes_send = createPostServerTests(`/type/union/mixed-types`, {
+  model: {
+    name: "test",
+  },
+  literal: "a",
+  int: 2,
+  boolean: true,
+  array: [
+    {
+      name: "test",
+    },
+    "a",
+    2,
+    true,
+  ],
+});

package/specs/versioning/added/main.tsp

@@ -0,0 +1,136 @@
+import "@typespec/http";
+import "@typespec/spector";
+import "@typespec/versioning";
+
+using Http;
+using Spector;
+using TypeSpec.Versioning;
+
+/**
+ * Test for the `@added` decorator.
+ */
+@service
+@versioned(Versions)
+@server(
+  "{endpoint}/versioning/added/api-version:{version}",
+  "Testserver endpoint",
+  {
+    /**
+     * Need to be set as 'http://localhost:3000' in client.
+     */
+    endpoint: url,
+
+    /**
+     * Need to be set as 'v1' or 'v2' in client.
+     */
+    version: Versions,
+  }
+)
+namespace Versioning.Added;
+
+/**
+ * The version of the API.
+ */
+enum Versions {
+  /**
+   * The version v1.
+   */
+  v1: "v1",
+
+  /**
+   * The version v2.
+   */
+  v2: "v2",
+}
+
+model ModelV1 {
+  prop: string;
+  enumProp: EnumV1;
+
+  @added(Versions.v2)
+  unionProp: UnionV1;
+}
+
+enum EnumV1 {
+  enumMemberV1,
+
+  @added(Versions.v2)
+  enumMemberV2,
+}
+
+@added(Versions.v2)
+model ModelV2 {
+  prop: string;
+  enumProp: EnumV2;
+  unionProp: UnionV2;
+}
+
+@added(Versions.v2)
+enum EnumV2 {
+  enumMember,
+}
+
+union UnionV1 {
+  string,
+
+  @added(Versions.v2)
+  V2Scalar,
+}
+
+@added(Versions.v2)
+union UnionV2 {
+  string,
+  int32,
+}
+
+@added(Versions.v2)
+scalar V2Scalar extends int32;
+
+@scenario
+@scenarioDoc("""
+  This operation should be generated with latest version's signature.
+  
+  Expected request body:
+  ```json
+  { "prop": "foo", "enumProp": "enumMemberV2", "unionProp": 10 }
+  ```
+  
+  Expected header:
+  header-v2=bar
+  
+  """)
+@route("/v1")
+@post
+op v1(@body body: ModelV1, @added(Versions.v2) @header headerV2: string): ModelV1;
+
+@scenario
+@scenarioDoc("""
+  This operation should only be generated with latest version.
+  
+  Expected request body:
+  ```json
+  { "prop": "foo", "enumProp": "enumMember", "unionProp": "bar" }
+  ```
+  """)
+@route("/v2")
+@added(Versions.v2)
+@post
+op v2(@body body: ModelV2): ModelV2;
+
+@added(Versions.v2)
+@scenario
+@scenarioDoc("""
+  This operation group should only be generated with latest version.
+  
+  Expected request body for v2InInterface:
+  ```json
+  { "prop": "foo", "enumProp": "enumMember", "unionProp": "bar" }
+  ```
+  
+  """)
+@route("/interface-v2")
+interface InterfaceV2 {
+  @post
+  @route("/v2")
+  v2InInterface(@body body: ModelV2): ModelV2;
+}

package/specs/versioning/added/mockapi.ts

@@ -0,0 +1,57 @@
+import { json, passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.Versioning_Added_v1 = passOnSuccess({
+  uri: `/versioning/added/api-version:v2/v1`,
+  method: `post`,
+  request: {
+    body: {
+      prop: "foo",
+      enumProp: "enumMemberV2",
+      unionProp: 10,
+    },
+    headers: {
+      "header-v2": "bar",
+    },
+  },
+  response: {
+    status: 200,
+    body: json({ prop: "foo", enumProp: "enumMemberV2", unionProp: 10 }),
+  },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.Versioning_Added_v2 = passOnSuccess({
+  uri: `/versioning/added/api-version:v2/v2`,
+  method: `post`,
+  request: {
+    body: {
+      prop: "foo",
+      enumProp: "enumMember",
+      unionProp: "bar",
+    },
+  },
+  response: {
+    status: 200,
+    body: json({ prop: "foo", enumProp: "enumMember", unionProp: "bar" }),
+  },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.Versioning_Added_InterfaceV2 = passOnSuccess({
+  uri: `/versioning/added/api-version:v2/interface-v2/v2`,
+  method: `post`,
+  request: {
+    body: {
+      prop: "foo",
+      enumProp: "enumMember",
+      unionProp: "bar",
+    },
+  },
+  response: {
+    status: 200,
+    body: json({ prop: "foo", enumProp: "enumMember", unionProp: "bar" }),
+  },
+  kind: "MockApiDefinition",
+});

package/specs/versioning/madeOptional/main.tsp

@@ -0,0 +1,65 @@
+import "@typespec/http";
+import "@typespec/spector";
+import "@typespec/versioning";
+
+using Http;
+using Spector;
+using TypeSpec.Versioning;
+
+/**
+ * Test for the `@madeOptional` decorator.
+ */
+@service
+@versioned(Versions)
+@server(
+  "{endpoint}/versioning/made-optional/api-version:{version}",
+  "Testserver endpoint",
+  {
+    /**
+     * Need to be set as 'http://localhost:3000' in client.
+     */
+    endpoint: url,
+
+    /**
+     * Need to be set as 'v1' or 'v2' in client.
+     */
+    version: Versions,
+  }
+)
+namespace Versioning.MadeOptional;
+
+/**
+ * The version of the API.
+ */
+enum Versions {
+  /**
+   * The version v1.
+   */
+  v1: "v1",
+
+  /**
+   * The version v2.
+   */
+  v2: "v2",
+}
+
+model TestModel {
+  prop: string;
+
+  @madeOptional(Versions.v2)
+  changedProp?: string;
+}
+
+@scenario
+@scenarioDoc("""
+  This operation should be generated with latest version's signature.
+  
+  Expected request body:
+  ```json
+  { "prop": "foo" }
+  ```
+  
+  """)
+@route("/test")
+@post
+op test(@body body: TestModel, @madeOptional(Versions.v2) @query param?: string): TestModel;

package/specs/versioning/madeOptional/mockapi.ts

@@ -0,0 +1,18 @@
+import { json, passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.Versioning_MadeOptional_test = passOnSuccess({
+  uri: `/versioning/made-optional/api-version:v2/test`,
+  method: `post`,
+  request: {
+    body: {
+      prop: "foo",
+    },
+  },
+  response: {
+    status: 200,
+    body: json({ prop: "foo" }),
+  },
+  kind: "MockApiDefinition",
+});