Parameter object missing fields - allowEmptyValue, deprecated.

.chronus/changes/ParameterObjectMissing-2024-10-8-14-57-38.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/openapi3"
+---
+
+Add support for `#deprecated` for OpenAPI3Parameter

packages/openapi3/src/openapi.ts

@@ -1249,6 +1249,10 @@ function createOAPIEmitter(
       Object.assign(param, attributes);
     }
 
+    if (isDeprecated(program, parameter.param)) {
+      param.deprecated = true;
+    }
+
     return param;
   }
 

packages/openapi3/test/openapi-output.test.ts

@@ -168,6 +168,53 @@ describe("openapi3: operations", () => {
 
     strictEqual(res.paths["/"].get.deprecated, true);
   });
+
+  it("deprecate inline parameters with #deprecated", async () => {
+    const res = await openApiFor(
+      `
+      op read(
+        #deprecated "Cannot use foo"
+        @query foo: string,
+      ): void;
+      `,
+    );
+
+    strictEqual(res.paths["/"].get.parameters[0].deprecated, true);
+  });
+
+  it("deprecate parameters with #deprecated", async () => {
+    const res = await openApiFor(
+      `
+      model PetId {
+        #deprecated "Cannot use foo"
+        @query foo: string;
+      }
+      op get(...PetId): void;
+      `,
+    );
+
+    strictEqual(res.paths["/"].get.parameters[0]["$ref"], "#/components/parameters/PetId");
+    strictEqual(res.components.parameters.PetId.deprecated, true);
+  });
+
+  it("deprecate one in multi parameters with #deprecated", async () => {
+    const res = await openApiFor(
+      `
+      model PetId {
+        #deprecated "Cannot use foo"
+        @query foo: string;
+
+        @path name: string,
+      }
+      op get(...PetId): void;
+      `,
+    );
+    const getThing = res.paths["/{name}"].get;
+    strictEqual(getThing.parameters[0]["$ref"], "#/components/parameters/PetId.foo");
+    strictEqual(getThing.parameters[1]["$ref"], "#/components/parameters/PetId.name");
+    strictEqual(res.components.parameters["PetId.foo"].deprecated, true);
+    strictEqual(res.components.parameters["PetId.name"].deprecated, undefined);
+  });
 });
 
 describe("openapi3: request", () => {

website/src/content/docs/docs/getting-started/typespec-for-openapi-dev.md

@@ -231,7 +231,7 @@ The fields in an OpenAPI operation object are specified with the following TypeS
 | `requestBody`             | parameter with `@body` decorator           | see [Request Body Object](#request-body-object-oas3)                         |
 | `responses`               | `op` return type(s)                        | see [Responses Object](#responses-object)                                    |
 | `callbacks`               |                                            | Not currently supported.                                                     |
-| `deprecated`              | `@deprecated` decorator                    |                                                                              |
+| `deprecated`              | `#deprecated` directive                    |                                                                              |
 | `security`                |                                            | see [Security Schemes Object](#securityDefinitions--securitySchemes-Object). |
 | `servers`                 | `@server` decorator                        | Can be specified multiple times.                                             |
 
@@ -308,7 +308,9 @@ The following fields of a parameter object are common to both OpenAPI v2 and v3:
 | `in`                      | decorator                    | `@query`, `@path`, `@header`, `@body`                                                                                        |
 | `description`             | `/** */` or `@doc` decorator |                                                                                                                              |
 | `required`                | from parameter "optionality" | a "?" following the parameter name indicates it is optional (`required: false`), otherwise it is required (`required: true`) |
-| `allowEmptyValue`         |                              | Not currently supported.                                                                                                     |
+| `allowEmptyValue`         |                              | Not supported, this field is `NOT RECOMMENDED` in OpenAPI.                                                                   |
+
+<!-- prettier-ignore-end -->
 
 ### OpenAPI v2
 
@@ -341,7 +343,7 @@ The following fields of a parameter object are specific to OpenAPI v3:
 | `style`                      | `format` parameter on `@query` or `@header` |                                     |
 | `explode`                    | `format` parameter on `@query` or `@header` |                                     |
 | `schema`                     | parameter schema                            | see [Schema Object](#schema-object) |
-| `deprecated`                 |                                             | Not currently supported.            |
+| `deprecated`                 | `#deprecated` directive.                    |                                     |
 | `example`                    |                                             | Not currently supported.            |
 | `examples`                   |                                             | Not currently supported.            |
 | `content`                    |                                             | Not currently supported.            |