Update docs for `@server` (#3960)

.chronus/changes/docs-servers-2024-6-24-14-48-1.md

@@ -0,0 +1,6 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/http"
+---
+

docs/libraries/http/reference/decorators.md

@@ -407,7 +407,7 @@ op getWidget(@path id: string): Widget;
 
 ### `@server` {#@TypeSpec.Http.server}
 
-Specify the endpoint for this service.
+Specify an endpoint for this service. Multiple `@server` decorators can be used to specify multiple endpoints.
 
 ```typespec
 @TypeSpec.Http.server(url: valueof string, description: valueof string, parameters?: Record<unknown>)
@@ -433,7 +433,7 @@ Specify the endpoint for this service.
 namespace PetStore;
 ```
 
-##### parameterized
+##### Parameterized
 
 ```typespec
 @server("https://{region}.foo.com", "Regional endpoint", {
@@ -442,6 +442,21 @@ namespace PetStore;
 })
 ```
 
+##### Multiple
+
+```typespec
+@service
+@server("https://example.com", "Standard endpoint")
+@server(
+  "https://{project}.private.example.com",
+  "Private project endpoint",
+  {
+    project: string,
+  }
+)
+namespace PetStore;
+```
+
 ### `@sharedRoute` {#@TypeSpec.Http.sharedRoute}
 
 `@sharedRoute` marks the operation as sharing a route path with other operations.

packages/http/README.md

@@ -455,7 +455,7 @@ op getWidget(@path id: string): Widget;
 
 #### `@server`
 
-Specify the endpoint for this service.
+Specify an endpoint for this service. Multiple `@server` decorators can be used to specify multiple endpoints.
 
 ```typespec
 @TypeSpec.Http.server(url: valueof string, description: valueof string, parameters?: Record<unknown>)
@@ -481,7 +481,7 @@ Specify the endpoint for this service.
 namespace PetStore;
 ```
 
-###### parameterized
+###### Parameterized
 
 ```typespec
 @server("https://{region}.foo.com", "Regional endpoint", {
@@ -490,6 +490,21 @@ namespace PetStore;
 })
 ```
 
+###### Multiple
+
+```typespec
+@service
+@server("https://example.com", "Standard endpoint")
+@server(
+  "https://{project}.private.example.com",
+  "Private project endpoint",
+  {
+    project: string,
+  }
+)
+namespace PetStore;
+```
+
 #### `@sharedRoute`
 
 `@sharedRoute` marks the operation as sharing a route path with other operations.

packages/http/generated-defs/TypeSpec.Http.ts

@@ -194,7 +194,7 @@ export type DeleteDecorator = (context: DecoratorContext, target: Operation) =>
 export type HeadDecorator = (context: DecoratorContext, target: Operation) => void;
 
 /**
- * Specify the endpoint for this service.
+ * Specify an endpoint for this service. Multiple `@server` decorators can be used to specify multiple endpoints.
  *
  * @param url Server endpoint
  * @param description Description of the endpoint
@@ -205,7 +205,7 @@ export type HeadDecorator = (context: DecoratorContext, target: Operation) => vo
  * @server("https://example.com", "Single server endpoint")
  * namespace PetStore;
  * ```
- * @example parameterized
+ * @example Parameterized
  *
  * ```typespec
  * @server("https://{region}.foo.com", "Regional endpoint", {
@@ -213,6 +213,15 @@ export type HeadDecorator = (context: DecoratorContext, target: Operation) => vo
  *   region?: string = "westus",
  * })
  * ```
+ * @example Multiple
+ * ```typespec
+ * @service
+ * @server("https://example.com", "Standard endpoint")
+ * @server("https://{project}.private.example.com", "Private project endpoint", {
+ *   project: string;
+ * })
+ * namespace PetStore;
+ * ```
  */
 export type ServerDecorator = (
   context: DecoratorContext,

packages/http/lib/decorators.tsp

@@ -220,19 +220,21 @@ extern dec delete(target: Operation);
 extern dec head(target: Operation);
 
 /**
- * Specify the endpoint for this service.
+ * Specify an endpoint for this service. Multiple `@server` decorators can be used to specify multiple endpoints.
+ *
  *  @param url Server endpoint
  *  @param description Description of the endpoint
  *  @param parameters Optional set of parameters used to interpolate the url.
  *
  * @example
+ *
  * ```typespec
  * @service
  * @server("https://example.com", "Single server endpoint")
  * namespace PetStore;
  * ```
  *
- * @example parameterized
+ * @example Parameterized
  *
  * ```typespec
  * @server("https://{region}.foo.com", "Regional endpoint", {
@@ -241,6 +243,16 @@ extern dec head(target: Operation);
  * })
  * ```
  *
+ * @example Multiple
+ * ```typespec
+ * @service
+ * @server("https://example.com", "Standard endpoint")
+ * @server("https://{project}.private.example.com", "Private project endpoint", {
+ *   project: string;
+ * })
+ * namespace PetStore;
+ * ```
+ *
  */
 extern dec server(
   target: Namespace,