From a8ce4b13943b8855d8fe7466d79a87c6cf6e210f Mon Sep 17 00:00:00 2001 From: Kanad Gupta <8854718+kanadgupta@users.noreply.github.com> Date: Thu, 9 May 2024 18:33:32 -0500 Subject: [PATCH] fix(oas/exampleGroups): properly set name for code samples (#873) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 🧰 Changes Fixes a few minuscule bugs with this `exampleGroups` object generation: - [x] We were previously adding names to nameless code samples regardless of their language (e.g., `Default #1` could be `shell` and the next nameless sample would be `Default #2` regardless of it was `shell` or not). We now properly split out our nameless sample counts by language - [x] We weren't properly tacking on these names to the code sample objects themselves - [x] Upgrades `oas-examples` to the latest This `exampleGroups` object has some wonky ergonomics that I'm already reckoning with but I can't seem to think of an alternative approach that warrants a breaking change. Stay tuned I guess? ## 🧬 QA & Testing Do tests still pass? --- package-lock.json | 6 ++--- .../src/operation/lib/get-example-groups.ts | 24 ++++++++++++------- .../get-example-groups.test.ts.snap | 4 +++- 3 files changed, 21 insertions(+), 13 deletions(-) diff --git a/package-lock.json b/package-lock.json index ef9d1563..4bf2d937 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2208,9 +2208,9 @@ } }, "node_modules/@readme/oas-examples": { - "version": "5.15.0", - "resolved": "https://registry.npmjs.org/@readme/oas-examples/-/oas-examples-5.15.0.tgz", - "integrity": "sha512-kYauwiJI5KMoDnaEQv8kDLbWHRuWM3/elzl+B+TykizrUw/NCs6SG52XAG4rGUxR1J5UmeG8bRo44mdPL30ZwA==", + "version": "5.15.1", + "resolved": "https://registry.npmjs.org/@readme/oas-examples/-/oas-examples-5.15.1.tgz", + "integrity": "sha512-eATSl305ZG5n9LOWx9ExTsy6ImtewyxuQCiMD5u70OQ3AlymSdylknNxpw+A+iS1K80LRYgUikizqNTESc5t2Q==", "dev": true }, "node_modules/@readme/oas-to-har": { diff --git a/packages/oas/src/operation/lib/get-example-groups.ts b/packages/oas/src/operation/lib/get-example-groups.ts index cc291841..27597578 100644 --- a/packages/oas/src/operation/lib/get-example-groups.ts +++ b/packages/oas/src/operation/lib/get-example-groups.ts @@ -105,8 +105,10 @@ function addMatchingResponseExamples(groups: ExampleGroups, operation: Operation * Returns a name for the given custom code sample. If there isn't already one defined, * we construct a fallback value based on where the sample is in the array. */ -function getDefaultName(sample: Extensions['code-samples'], count: number): string { - return sample.name && sample.name.length > 0 ? sample.name : `Default${count > 1 ? ` #${count}` : ''}`; +function getDefaultName(sample: Extensions['code-samples'], count: Record): string { + return sample.name && sample.name.length > 0 + ? sample.name + : `Default${count[sample.language] > 1 ? ` #${count[sample.language]}` : ''}`; } /** @@ -121,32 +123,36 @@ function getDefaultName(sample: Extensions['code-samples'], count: number): stri * (i.e., a response example with the same key in the `examples` map). */ export function getExampleGroups(operation: Operation): ExampleGroups { - let namelessCodeSamples = 0; + const namelessCodeSampleCounts: Record = {}; const groups: ExampleGroups = {}; // add custom code samples const codeSamples = getExtension('code-samples', operation.api, operation) as Extensions['code-samples'][]; codeSamples?.forEach(sample => { - namelessCodeSamples += 1; - const name = getDefaultName(sample, namelessCodeSamples); + if (namelessCodeSampleCounts[sample.language]) { + namelessCodeSampleCounts[sample.language] += 1; + } else { + namelessCodeSampleCounts[sample.language] = 1; + } + const name = getDefaultName(sample, namelessCodeSampleCounts); // sample contains `correspondingExample` key if (groups[sample.correspondingExample]?.customCodeSamples?.length) { - groups[sample.correspondingExample].customCodeSamples.push(sample); + groups[sample.correspondingExample].customCodeSamples.push({ ...sample, name }); } else if (sample.correspondingExample) { groups[sample.correspondingExample] = { name, - customCodeSamples: [sample], + customCodeSamples: [{ ...sample, name }], }; } // sample does not contain a corresponding response example else if (groups[noCorrespondingResponseKey]?.customCodeSamples?.length) { - groups[noCorrespondingResponseKey].customCodeSamples.push(sample); + groups[noCorrespondingResponseKey].customCodeSamples.push({ ...sample, name }); } else { groups[noCorrespondingResponseKey] = { name, - customCodeSamples: [sample], + customCodeSamples: [{ ...sample, name }], }; } }); diff --git a/packages/oas/test/operation/lib/__snapshots__/get-example-groups.test.ts.snap b/packages/oas/test/operation/lib/__snapshots__/get-example-groups.test.ts.snap index 10ebbd7c..422628d4 100644 --- a/packages/oas/test/operation/lib/__snapshots__/get-example-groups.test.ts.snap +++ b/packages/oas/test/operation/lib/__snapshots__/get-example-groups.test.ts.snap @@ -190,10 +190,11 @@ exports[`custom code samples with matching response examples 1`] = ` "NoCorrespondingResponseForCustomCodeSample": { "customCodeSamples": [ { - "code": "# This custom cURL snippet does not have a custom name so it has the name of "Default #2". + "code": "# This custom cURL snippet does not have a custom name so it has the name of "Default #3". curl -X POST https://api.example.com/v2/alert", "language": "curl", + "name": "Default #3", }, ], "name": "Default #3", @@ -291,6 +292,7 @@ exports[`custom code samples with no matching response examples 1`] = ` curl -X POST https://api.example.com/v2/alert", "language": "curl", + "name": "Default #2", }, ], "name": "Custom cURL snippet",