[openapi3] add support for parameter examples via @opExample #7403
Conversation
chrisradek
requested review from
bterlson,
markcowl,
timotheeguerin,
witemple-msft and
AlitzelMendez
as code owners
|
All changed packages have been documented.
|
packages/openapi3/src/examples.ts
Outdated
| if (!isSerializableScalarValue(value)) continue; | ||
| pairs.push(`${value.value}`); | ||
| } | ||
| return tk.value.createString(`?${name}=${encodeURIComponent(pairs.join(delimiter))}`); |
There was a problem hiding this comment.
I need to double check if there's anywhere else I need to encode URI components.
| { | ||
| desc: "form (undefined)", | ||
| param: `@cookie color: string | null`, | ||
| paramExample: `null`, |
There was a problem hiding this comment.
shouldn't this test case be not passing the example value?
otherwise for null i feel like it probably still serialize as color=null (same for all (undefined)) cases
There was a problem hiding this comment.
There's one more column to the tables, undefined, that I didn't include in the comments.
The undefined column replaces the empty column in previous versions of this specification in order to better align with [RFC6570] Section 2.3 terminology, which describes certain values including but not limited to null as “undefined” values with special handling; notably, the empty string is not undefined
So I took the value from the undefined columns for these cases.
(link to table: https://spec.openapis.org/oas/v3.0.4.html#style-examples)
| @@ -234,4 +234,385 @@ worksFor(["3.0.0", "3.1.0"], ({ openApiFor }) => { | |||
| age: 2, | |||
| }); | |||
| }); | |||
|
|
|||
| describe("parameters", () => { | |||
| it.each([ | |||
There was a problem hiding this comment.
can each of the it.each be grouped under a describe with the current test used in the it message and replace the message of the it just as the desc defined
|
You can try these changes here
|
| op getColors(${param}): void; | ||
| `, | ||
| ); | ||
| expect((res.paths[`/{color}`].get?.parameters[0] as OpenAPI3Parameter).example).toEqual( |
There was a problem hiding this comment.
should you also have a test to make sure it works with multiple examples
| @@ -307,4 +307,47 @@ worksFor(["3.0.0", "3.1.0"], ({ openApiFor }) => { | |||
| }, | |||
| }); | |||
| }); | |||
|
|
|||
| it("supports encoding", async () => { | |||
There was a problem hiding this comment.
should have a test also that test that by default headers are encoded as rfc7231
Fixes #3873
This PR adds support for generating parameter examples in openapi3.
Notes:
From the OpenAPI spec (https://spec.openapis.org/oas/v3.0.4.html#fixed-fields-for-use-with-schema):
The parameter-level examples are meant to be serialized as they would appear over the wire. This means in some cases, they conflict with the parameter schema. For example, when a header parameter is an array.
The OpenAPI spec provides a table that shows what an example should look like for any given parameter style:
https://spec.openapis.org/oas/v3.0.4.html#style-examples