feat: enrich snippets files

scripts/package.json

@@ -25,6 +25,7 @@
     "@actions/core": "1.11.1",
     "@actions/exec": "1.1.1",
     "@actions/io": "1.1.3",
+    "@apidevtools/json-schema-ref-parser": "^11.7.2",
     "@har-sdk/oas": "2.10.0",
     "@octokit/rest": "21.0.2",
     "@types/express": "5.0.0",

scripts/specs/format.ts

@@ -52,7 +52,7 @@ export async function bundleSpecsForDoc(bundledPath: string, clientName: string)
   const tagsDefinitions = bundledSpec.tags;
   const codeSamples = await transformGeneratedSnippetsToCodeSamples(clientName);
 
-  await bundleCodeSamplesForDoc(JSON.parse(JSON.stringify(codeSamples)), clientName);
+  await bundleCodeSamplesForDoc(bundledSpec, JSON.parse(JSON.stringify(codeSamples)), clientName);
 
   for (const [pathKey, pathMethods] of Object.entries(bundledSpec.paths)) {
     for (const [method, specMethod] of Object.entries(pathMethods)) {

scripts/specs/snippets.ts

@@ -1,9 +1,10 @@
+import $RefParser from '@apidevtools/json-schema-ref-parser';
 import fsp from 'fs/promises';
 
-import { GENERATORS, capitalize, createClientName, exists, toAbsolutePath } from '../common.js';
-import type { Language } from '../types.js';
+import { GENERATORS, LANGUAGES, capitalize, createClientName, exists, toAbsolutePath } from '../common.js';
+import type { Language, Spec } from '../types.js';
 
-import type { CodeSamples, OpenAPICodeSample, SampleForOperation } from './types.js';
+import type { CodeSamples, CodeSamplesWithAPIDefinition, OpenAPICodeSample, SampleForOperation } from './types.js';
 
 export function getCodeSampleLabel(language: Language): OpenAPICodeSample['label'] {
   switch (language) {
@@ -19,7 +20,8 @@ export function getCodeSampleLabel(language: Language): OpenAPICodeSample['label
 }
 
 // Iterates over the result of `transformSnippetsToCodeSamples` in order to generate a JSON file for the doc to consume.
-export async function bundleCodeSamplesForDoc(codeSamples: CodeSamples, clientName: string): Promise<void> {
+export async function bundleCodeSamplesForDoc(spec: Spec, codeSamples: CodeSamples, clientName: string): Promise<void> {
+  // first we build the end JSON file with our given code samples
   for (const [language, operationWithSamples] of Object.entries(codeSamples)) {
     for (const [operation, samples] of Object.entries(operationWithSamples)) {
       if (operation === 'import') {
@@ -48,7 +50,33 @@ export async function bundleCodeSamplesForDoc(codeSamples: CodeSamples, clientNa
     }
   }
 
-  await fsp.writeFile(toAbsolutePath(`docs/bundled/${clientName}-snippets.json`), JSON.stringify(codeSamples, null, 2));
+  const codeSamplesWithParameters = { ...codeSamples } as CodeSamplesWithAPIDefinition;
+  const dereferencedSpec = (await $RefParser.dereference(spec, {
+    mutateInputSchema: false,
+    dereference: { circular: 'ignore' },
+  })) as Spec;
+
+  for (const [_, operations] of Object.entries(dereferencedSpec.paths)) {
+    for (const operation of Object.values(operations)) {
+      for (const lang of LANGUAGES) {
+        if (operation.operationId in codeSamplesWithParameters[lang]) {
+          codeSamplesWithParameters[lang][operation.operationId].parameters = operation.parameters || [];
+          codeSamplesWithParameters[lang][operation.operationId].responses = operation.responses || {};
+
+          if (operation.requestBody?.content?.['application/json']?.schema?.properties) {
+            codeSamplesWithParameters[lang][operation.operationId].parameters.push(
+              ...new Set([operation.requestBody?.content?.['application/json']?.schema?.properties]),
+            );
+          }
+        }
+      }
+    }
+  }
+
+  await fsp.writeFile(
+    toAbsolutePath(`docs/bundled/${clientName}-snippets.json`),
+    JSON.stringify(codeSamplesWithParameters, null, 2),
+  );
 }
 
 // Reads the generated `docs/snippets/` file for every languages of the given `clientName` and builds an hashmap of snippets per operationId per language.

scripts/specs/types.ts

@@ -6,12 +6,19 @@ export type BaseBuildSpecsOptions = {
   useCache: boolean;
 };
 
+export type SampleForOperationWithAPIDefinition = SampleForOperation & {
+  parameters: Array<Record<string, any>>;
+  responses: Record<string, Record<string, any>>;
+};
+export type CodeSamplesWithAPIDefinition = Record<Language, Record<string, SampleForOperationWithAPIDefinition>>;
+
 export type SampleForOperation = Record<string, string>;
 export type CodeSamples = Record<Language, Record<string, SampleForOperation>>;
 
 export type OpenAPICodeSample = {
   lang:
     | 'c'
+    | 'cURL'
     | 'c++'
     | 'coffeescript'
     | 'csharp'
@@ -38,6 +45,7 @@ export type OpenAPICodeSample = {
     | 'typescript';
   label:
     | 'C'
+    | 'curl'
     | 'C#'
     | 'C++'
     | 'CoffeeScript'

scripts/types.ts

@@ -1,6 +1,6 @@
 import type config from '../config/clients.config.json';
 
-import type { CodeSamples } from './specs/types.js';
+import type { OpenAPICodeSample } from './specs/types.js';
 
 /**
  * Config.
@@ -46,6 +46,8 @@ export type Spec = {
   paths: Path;
   components: {
     schemas: Record<string, any>;
+    parameters: Record<string, any>;
+    responses: Record<string, any>;
     securitySchemes: Partial<{ appId?: Record<string, any>; apiKey?: Record<string, any> }>;
   };
 };
@@ -77,11 +79,17 @@ type Method = 'delete' | 'get' | 'options' | 'patch' | 'post' | 'put';
 /**
  * Paths of a spec.
  */
-type Path = Record<
-  Method,
-  Record<string, any> & {
-    operationId: string;
-    'x-codeSamples': CodeSamples[];
-    summary: string;
-  }
->;
+export type Path = Record<string, Record<Method, Operation>>;
+
+export type Operation = {
+  operationId: string;
+  'x-codeSamples': OpenAPICodeSample[];
+  summary: string;
+  requestBody?: {
+    required: boolean;
+    description: string;
+    content?: { 'application/json'?: { schema?: { properties?: Record<string, any> } } };
+  };
+  parameters: Array<Record<string, any>>;
+  responses: Record<string, Record<string, any>>;
+} & Record<string, unknown>;