The description parameter of @server should be optional (#4804)

#2229 --------- Co-authored-by: Kyle Zhang <[email protected]> Co-authored-by: Timothee Guerin <[email protected]>
microsoft · Oct 29, 2024 · 2f896c7 · 2f896c7
1 parent a4bab81
commit 2f896c7
Show file tree

Hide file tree

Showing 8 changed files with 78 additions and 24 deletions.
diff --git a/.chronus/changes/serverDescOption-2024-9-21-17-14-49.md b/.chronus/changes/serverDescOption-2024-9-21-17-14-49.md
@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http"
+---
+
+The description parameter of `@server` is now optional.
diff --git a/docs/libraries/http/reference/decorators.md b/docs/libraries/http/reference/decorators.md
@@ -412,7 +412,7 @@ Defines the relative route URI template for the target operation as defined by [
 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>)
+@TypeSpec.Http.server(url: valueof string, description?: valueof string, parameters?: Record<unknown>)
 ```
 
 #### Target
@@ -429,6 +429,14 @@ Specify an endpoint for this service. Multiple `@server` decorators can be used
 
 #### Examples
 
+```typespec
+@service
+@server("https://example.com")
+namespace PetStore;
+```
+
+##### With a description
+
 ```typespec
 @service
 @server("https://example.com", "Single server endpoint")

diff --git a/packages/http/README.md b/packages/http/README.md
@@ -460,7 +460,7 @@ Defines the relative route URI template for the target operation as defined by [
 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>)
+@TypeSpec.Http.server(url: valueof string, description?: valueof string, parameters?: Record<unknown>)
 ```
 
 ##### Target
@@ -477,6 +477,14 @@ Specify an endpoint for this service. Multiple `@server` decorators can be used
 
 ##### Examples
 
+```typespec
+@service
+@server("https://example.com")
+namespace PetStore;
+```
+
+###### With a description
+
 ```typespec
 @service
 @server("https://example.com", "Single server endpoint")

diff --git a/packages/http/generated-defs/TypeSpec.Http.ts b/packages/http/generated-defs/TypeSpec.Http.ts
@@ -215,6 +215,13 @@ export type HeadDecorator = (context: DecoratorContext, target: Operation) => vo
  * @example
  * ```typespec
  * @service
+ * @server("https://example.com")
+ * namespace PetStore;
+ * ```
+ * @example With a description
+ *
+ * ```typespec
+ * @service
  * @server("https://example.com", "Single server endpoint")
  * namespace PetStore;
  * ```
@@ -240,7 +247,7 @@ export type ServerDecorator = (
   context: DecoratorContext,
   target: Namespace,
   url: string,
-  description: string,
+  description?: string,
   parameters?: Type,
 ) => void;
 

diff --git a/packages/http/lib/decorators.tsp b/packages/http/lib/decorators.tsp
@@ -270,6 +270,14 @@ extern dec head(target: Operation);
  *
  * ```typespec
  * @service
+ * @server("https://example.com")
+ * namespace PetStore;
+ * ```
+ *
+ * @example With a description
+ *
+ * ```typespec
+ * @service
  * @server("https://example.com", "Single server endpoint")
  * namespace PetStore;
  * ```
@@ -297,7 +305,7 @@ extern dec head(target: Operation);
 extern dec server(
   target: Namespace,
   url: valueof string,
-  description: valueof string,
+  description?: valueof string,
   parameters?: Record<unknown>
 );
 

diff --git a/packages/http/src/decorators.ts b/packages/http/src/decorators.ts
@@ -419,7 +419,7 @@ const VERB_DECORATORS = [$get, $head, $post, $put, $patch, $delete];
 
 export interface HttpServer {
   url: string;
-  description: string;
+  description?: string;
   parameters: Map<string, ModelProperty>;
 }
 
@@ -434,7 +434,7 @@ export const $server: ServerDecorator = (
   context: DecoratorContext,
   target: Namespace,
   url: string,
-  description: string,
+  description?: string,
   parameters?: Type,
 ) => {
   const params = extractParamsFromPath(url);
@@ -456,11 +456,7 @@ export const $server: ServerDecorator = (
     servers = [];
     context.program.stateMap(HttpStateKeys.servers).set(target, servers);
   }
-  servers.push({
-    url,
-    description,
-    parameters: parameterMap,
-  });
+  servers.push({ url, description, parameters: parameterMap });
 };
 
 export function getServers(program: Program, type: Namespace): HttpServer[] | undefined {

diff --git a/packages/http/test/http-decorators.test.ts b/packages/http/test/http-decorators.test.ts
@@ -638,18 +638,6 @@ describe("http: decorators", () => {
       });
     });
 
-    it("emit diagnostics when description is not provided", async () => {
-      const diagnostics = await runner.diagnose(`
-        @server("https://example.com")
-        namespace MyService {}
-      `);
-
-      expectDiagnostics(diagnostics, {
-        code: "invalid-argument-count",
-        message: "Expected 2-3 arguments, but got 1.",
-      });
-    });
-
     it("emit diagnostics when parameters is not a model", async () => {
       const diagnostics = await runner.diagnose(`
         @server("https://example.com", "My service url", 123)
@@ -673,6 +661,22 @@ describe("http: decorators", () => {
       });
     });
 
+    it("define a simple server without description", async () => {
+      const { MyService } = (await runner.compile(`
+        @server("https://example.com")
+        @test namespace MyService {}
+      `)) as { MyService: Namespace };
+
+      const servers = getServers(runner.program, MyService);
+      deepStrictEqual(servers, [
+        {
+          description: undefined,
+          parameters: new Map(),
+          url: "https://example.com",
+        },
+      ]);
+    });
+
     it("define a simple server with a fixed url", async () => {
       const { MyService } = (await runner.compile(`
         @server("https://example.com", "My service url")

diff --git a/packages/openapi3/test/servers.test.ts b/packages/openapi3/test/servers.test.ts
@@ -4,7 +4,23 @@ import { describe, it } from "vitest";
 import { diagnoseOpenApiFor, openApiFor } from "./test-host.js";
 
 describe("openapi3: servers", () => {
-  it("set a basic server", async () => {
+  it("set a basic server(url)", async () => {
+    const res = await openApiFor(
+      `
+      @service({title: "My service"})
+      @server("https://example.com")
+      namespace MyService {}
+      `,
+    );
+    deepStrictEqual(res.servers, [
+      {
+        url: "https://example.com",
+        variables: {},
+      },
+    ]);
+  });
+
+  it("set a basic server(url and desc)", async () => {
     const res = await openApiFor(
       `
       @service({title: "My service"})