Add @sharedRoute decorator and decouple it from @route

common/changes/@typespec/http/split-shared-route_2023-04-06-12-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "Add `@sharedRoute` decorator for marking operations as sharing a route with other operations",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}

common/changes/@typespec/http/split-shared-route_2023-04-18-14-06.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "Deprecate the `shared` option in the `@route` decorator.  `@sharedRoute` is the new way to accomplish the same behavior.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}

common/changes/@typespec/openapi3/split-shared-route_2023-04-18-14-27.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/openapi3",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/openapi3"
+}

common/changes/@typespec/rest/split-shared-route_2023-04-07-14-49.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/rest",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/rest"
+}

common/changes/@typespec/rest/split-shared-route_2023-04-18-14-06.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/rest",
+      "comment": "Add validation to ensure that @action or @collectionAction operations have a specified name when used with @sharedRoute",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/rest"
+}

docs/standard-library/http/reference/decorators.md

@@ -237,7 +237,7 @@ dec TypeSpec.Http.query(target: ModelProperty, queryNameOrOptions?: string | Typ
 
 ### `@route` {#@TypeSpec.Http.route}
 
-`@route` defines the relative route URI for the target operation
+Defines the relative route URI for the target operation
 
 The first argument should be a URI fragment that may contain one or more path parameter fields.
 If the namespace or interface that contains the operation is also marked with a `@route` decorator,
@@ -246,19 +246,19 @@ it will be used as a prefix to the route URI of the operation.
 `@route` can only be applied to operations, namespaces, and interfaces.
 
 ```typespec
-dec TypeSpec.Http.route(entity: unknown, path: string, parameters?: object)
+dec TypeSpec.Http.route(target: Namespace | Interface | Operation, path: string, options?: (anonymous model))
 ```
 
 #### Target
 
-`(intrinsic) unknown`
+`union Namespace | Interface | Operation`
 
 #### Parameters
 
-| Name       | Type            | Description                                                                                                                                           |
-| ---------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| path       | `scalar string` | Relative route path. Cannot include query parameters.                                                                                                 |
-| parameters | `model object`  | Optional set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations. |
+| Name    | Type                      | Description                                           |
+| ------- | ------------------------- | ----------------------------------------------------- |
+| path    | `scalar string`           | Relative route path. Cannot include query parameters. |
+| options | `model (anonymous model)` |                                                       |
 
 ### `@server` {#@TypeSpec.Http.server}
 
@@ -280,6 +280,33 @@ dec TypeSpec.Http.server(target: Namespace, url: string, description: string, pa
 | description | `scalar string` | Description of the endpoint                             |
 | parameters  | `model object`  | Optional set of parameters used to interpolate the url. |
 
+### `@sharedRoute` {#@TypeSpec.Http.sharedRoute}
+
+`@sharedRoute` marks the operation as sharing a route path with other operations.
+
+When an operation is marked with `@sharedRoute`, it enables other operations to share the same
+route path as long as those operations are also marked with `@sharedRoute`.
+
+`@sharedRoute` can only be applied directly to operations.
+
+```typespec
+@sharedRoute
+@route("/widgets")
+op getWidget(@path id: string): Widget;
+```
+
+```typespec
+dec TypeSpec.Http.sharedRoute(target: Operation)
+```
+
+#### Target
+
+`Operation`
+
+#### Parameters
+
+None
+
 ### `@statusCode` {#@TypeSpec.Http.statusCode}
 
 Specify the status code for this response. Property type must be a status code integer or a union of status code integer.

docs/standard-library/http/reference/index.md

@@ -22,6 +22,7 @@ toc_max_heading_level: 3
 - [`@query`](./decorators.md#@TypeSpec.Http.query)
 - [`@route`](./decorators.md#@TypeSpec.Http.route)
 - [`@server`](./decorators.md#@TypeSpec.Http.server)
+- [`@sharedRoute`](./decorators.md#@TypeSpec.Http.sharedRoute)
 - [`@statusCode`](./decorators.md#@TypeSpec.Http.statusCode)
 - [`@useAuth`](./decorators.md#@TypeSpec.Http.useAuth)
 

packages/http/lib/http-decorators.tsp

@@ -206,7 +206,7 @@ extern dec useAuth(target: Namespace, auth: object | Union | object[]);
 extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean);
 
 /**
- * `@route` defines the relative route URI for the target operation
+ * Defines the relative route URI for the target operation
  *
  * The first argument should be a URI fragment that may contain one or more path parameter fields.
  * If the namespace or interface that contains the operation is also marked with a `@route` decorator,
@@ -216,5 +216,34 @@ extern dec includeInapplicableMetadataInPayload(target: unknown, value: boolean)
  *
  * @param path Relative route path. Cannot include query parameters.
  * @param parameters Optional set of parameters used to configure the route. Supports `{shared: true}` which indicates that the route may be shared by several operations.
+ *
+ * @example
+ *
+ * ```typespec
+ * @route("/widgets")
+ * op getWidget(@path id: string): Widget;
+ * ```
+ */
+extern dec route(
+  target: Namespace | Interface | Operation,
+  path: string,
+  options?: {
+    shared?: boolean,
+  }
+);
+
+/**
+ * `@sharedRoute` marks the operation as sharing a route path with other operations.
+ *
+ * When an operation is marked with `@sharedRoute`, it enables other operations to share the same
+ * route path as long as those operations are also marked with `@sharedRoute`.
+ *
+ * `@sharedRoute` can only be applied directly to operations.
+ *
+ * ```typespec
+ * @sharedRoute
+ * @route("/widgets")
+ * op getWidget(@path id: string): Widget;
+ * ```
  */
-extern dec route(entity: unknown, path: string, parameters?: object);
+extern dec sharedRoute(target: Operation);

packages/http/src/decorators.ts

@@ -1,25 +1,26 @@
 import {
-  createDiagnosticCollector,
   DecoratorContext,
   Diagnostic,
   DiagnosticTarget,
-  getDoc,
-  isArrayModelType,
   Model,
   ModelProperty,
   Namespace,
   Operation,
   Program,
-  setTypeSpecNamespace,
   Tuple,
   Type,
-  typespecTypeToJson,
   Union,
+  createDiagnosticCollector,
+  getDoc,
+  isArrayModelType,
+  reportDeprecated,
+  setTypeSpecNamespace,
+  typespecTypeToJson,
   validateDecoratorTarget,
   validateDecoratorUniqueOnNode,
 } from "@typespec/compiler";
 import { createDiagnostic, createStateSymbol, reportDiagnostic } from "./lib.js";
-import { setRoute } from "./route.js";
+import { setRoute, setSharedRoute } from "./route.js";
 import {
   AuthenticationOption,
   HeaderFieldOptions,
@@ -559,23 +560,6 @@ export function getAuthentication(
   return program.stateMap(authenticationKey).get(namespace);
 }
 
-function extractSharedValue(context: DecoratorContext, parameters?: Model): boolean {
-  const sharedType = parameters?.properties.get("shared")?.type;
-  if (sharedType === undefined) {
-    return false;
-  }
-  switch (sharedType.kind) {
-    case "Boolean":
-      return sharedType.value;
-    default:
-      reportDiagnostic(context.program, {
-        code: "shared-boolean",
-        target: sharedType,
-      });
-      return false;
-  }
-}
-
 /**
  * `@route` defines the relative route URI for the target operation
  *
@@ -588,12 +572,40 @@ function extractSharedValue(context: DecoratorContext, parameters?: Model): bool
 export function $route(context: DecoratorContext, entity: Type, path: string, parameters?: Model) {
   validateDecoratorUniqueOnNode(context, entity, $route);
 
+  // Handle the deprecated `shared` option
+  let shared = false;
+  const sharedValue = parameters?.properties.get("shared")?.type;
+  if (sharedValue !== undefined) {
+    reportDeprecated(
+      context.program,
+      "The `shared` option is deprecated, use the `@sharedRoute` decorator instead.",
+      entity
+    );
+
+    // The type checker should have raised a diagnostic if the value isn't boolean
+    if (sharedValue.kind === "Boolean") {
+      shared = sharedValue.value;
+    }
+  }
+
   setRoute(context, entity, {
     path,
-    shared: extractSharedValue(context, parameters),
+    shared,
   });
 }
 
+/**
+ * `@sharedRoute` marks the operation as sharing a route path with other operations.
+ *
+ * When an operation is marked with `@sharedRoute`, it enables other operations to share the same
+ * route path as long as those operations are also marked with `@sharedRoute`.
+ *
+ * `@sharedRoute` can only be applied directly to operations.
+ */
+export function $sharedRoute(context: DecoratorContext, entity: Operation) {
+  setSharedRoute(context.program, entity);
+}
+
 const includeInapplicableMetadataInPayloadKey = createStateSymbol(
   "includeInapplicableMetadataInPayload"
 );

packages/http/src/lib.ts

@@ -100,12 +100,6 @@ const libDefinition = {
         default: paramMessage`@useAuth ${"kind"} only accept Auth model, Tuple of auth model or union of auth model.`,
       },
     },
-    "shared-boolean": {
-      severity: "error",
-      messages: {
-        default: "shared parameter must be a boolean.",
-      },
-    },
     "shared-inconsistency": {
       severity: "error",
       messages: {

packages/http/src/route.ts

@@ -216,28 +216,43 @@ export function setRoute(context: DecoratorContext, entity: Type, details: Route
   const state = context.program.stateMap(routesKey);
 
   if (state.has(entity) && entity.kind === "Namespace") {
-    const existingValue: RoutePath = state.get(entity);
-    if (existingValue.path !== details.path) {
+    const existingPath: string | undefined = state.get(entity);
+    if (existingPath !== details.path) {
       reportDiagnostic(context.program, {
         code: "duplicate-route-decorator",
         messageId: "namespace",
         target: entity,
       });
     }
   } else {
-    state.set(entity, details);
+    state.set(entity, details.path);
+    if (entity.kind === "Operation" && details.shared) {
+      setSharedRoute(context.program, entity as Operation);
+    }
   }
 }
 
+const sharedRoutesKey = createStateSymbol("sharedRoutes");
+
+export function setSharedRoute(program: Program, operation: Operation) {
+  program.stateMap(sharedRoutesKey).set(operation, true);
+}
+
 export function isSharedRoute(program: Program, operation: Operation): boolean {
-  return program.stateMap(routesKey).get(operation)?.shared;
+  return program.stateMap(sharedRoutesKey).get(operation) === true;
 }
 
 export function getRoutePath(
   program: Program,
   entity: Namespace | Interface | Operation
 ): RoutePath | undefined {
-  return program.stateMap(routesKey).get(entity);
+  const path = program.stateMap(routesKey).get(entity);
+  return path
+    ? {
+        path,
+        shared: entity.kind === "Operation" && isSharedRoute(program, entity as Operation),
+      }
+    : undefined;
 }
 
 const routeOptionsKey = createStateSymbol("routeOptions");

packages/http/test/http-decorators.test.ts

@@ -245,10 +245,23 @@ describe("http: decorators", () => {
       ]);
     });
 
-    it("emit diagnostics when not all duplicated routes are declared shared", async () => {
+    it("emits diagnostic when deprecated `shared` option is used", async () => {
       const diagnostics = await runner.diagnose(`
         @route("/test", { shared: true }) op test(): string;
-        @route("/test", { shared: true }) op test2(): string;
+      `);
+      expectDiagnostics(diagnostics, [
+        {
+          code: "deprecated",
+          message:
+            "Deprecated: The `shared` option is deprecated, use the `@sharedRoute` decorator instead.",
+        },
+      ]);
+    });
+
+    it("emit diagnostics when not all duplicated routes are declared shared", async () => {
+      const diagnostics = await runner.diagnose(`
+        @route("/test") @sharedRoute op test(): string;
+        @route("/test") @sharedRoute op test2(): string;
         @route("/test") op test3(): string;
       `);
       expectDiagnostics(diagnostics, [
@@ -261,8 +274,8 @@ describe("http: decorators", () => {
 
     it("do not emit diagnostics when duplicated shared routes are applied", async () => {
       const diagnostics = await runner.diagnose(`
-        @route("/test", {shared: true}) op test(): string;
-        @route("/test", {shared: true}) op test2(): string;
+        @route("/test") @sharedRoute op test(): string;
+        @route("/test") @sharedRoute op test2(): string;
       `);
 
       expectDiagnosticEmpty(diagnostics);
@@ -274,8 +287,8 @@ describe("http: decorators", () => {
       `);
       expectDiagnostics(diagnostics, [
         {
-          code: "@typespec/http/shared-boolean",
-          message: `shared parameter must be a boolean.`,
+          code: "invalid-argument",
+          message: `Argument '(anonymous model)' is not assignable to parameter of type '(anonymous model)'`,
         },
       ]);
     });