@pikku/openapi-parser 0.12.4 → 0.12.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pikku/openapi-parser
 
+## 0.12.6
+
+### Patch Changes
+
+- a57ff11: Add Swagger 2.0 support: extract requestBody from body parameters, responseSchema from direct response schema, and component schemas from definitions. Fix duplicate .describe() on request body properties.
+
+## 0.12.5
+
+### Patch Changes
+
+- 8552e18: Don't generate `output: z.void()` for operations without response schemas — omit the field instead
+
 ## 0.12.4
 
 ### Patch Changes

package/dist/codegen.js

@@ -119,7 +119,10 @@ function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
     const outputName = `${pascalName}Output`;
     // Determine error imports needed
     const errorClasses = getErrorClassesForResponses(parsed.errorResponses);
-    lines.push("import { z } from 'zod'");
+    const needsZod = hasInput || !!parsed.responseSchema;
+    if (needsZod) {
+        lines.push("import { z } from 'zod'");
+    }
     lines.push("import { pikkuSessionlessFunc } from '#pikku'");
     if (errorClasses.length > 0) {
         lines.push(`import { ${errorClasses.join(', ')} } from '@pikku/core/errors'`);
@@ -148,9 +151,6 @@ function generateFunctionFile(named, parsed, vars, ctx, spec, flags) {
     if (parsed.responseSchema) {
         funcConfig.push(`  output: ${outputName},`);
     }
-    else {
-        funcConfig.push('  output: z.void(),');
-    }
     if (errorClasses.length > 0) {
         funcConfig.push(`  errors: [${errorClasses.join(', ')}],`);
     }
@@ -186,10 +186,7 @@ function buildInputSchema(parsed, ctx) {
                     continue;
                 const isOptional = !requiredSet.has(key);
                 const zodCode = schemaToZod(propSchema, ctx, { optional: isOptional });
-                const withDesc = propSchema.description
-                    ? `${zodCode}.describe(${JSON.stringify(propSchema.description)})`
-                    : zodCode;
-                props.push(`  ${safeKey(key)}: ${withDesc},`);
+                props.push(`  ${safeKey(key)}: ${zodCode},`);
             }
         }
         else {

package/dist/parse-openapi.js

@@ -38,12 +38,11 @@ export async function parseOpenAPISpec(filePath) {
     const authType = detectAuthType(doc);
     const securitySchemes = extractSecuritySchemes(doc);
     const tagDescriptions = extractTagDescriptions(doc);
-    // Extract component schemas
+    // Extract component schemas (OpenAPI 3.x: components.schemas, Swagger 2.x: definitions)
     const componentSchemas = {};
-    if (doc.components?.schemas) {
-        for (const [name, schema] of Object.entries(doc.components.schemas)) {
-            componentSchemas[name] = schema;
-        }
+    const rawSchemas = doc.components?.schemas ?? doc.definitions ?? {};
+    for (const [name, schema] of Object.entries(rawSchemas)) {
+        componentSchemas[name] = schema;
     }
     // Extract operations (skip deprecated)
     const operations = [];
@@ -59,7 +58,9 @@ export async function parseOpenAPISpec(filePath) {
                 if (op.deprecated === true)
                     continue;
                 const allParams = [...sharedParams, ...(op.parameters ?? [])];
-                const body = op.requestBody;
+                // OpenAPI 3.x: op.requestBody, Swagger 2.x: parameters[].in === 'body'
+                const body3 = op.requestBody;
+                const body2 = allParams.find((p) => p.in === 'body');
                 operations.push({
                     operationId: op.operationId,
                     method,
@@ -71,8 +72,8 @@ export async function parseOpenAPISpec(filePath) {
                     queryParams: extractParams(allParams, 'query'),
                     headerParams: extractParams(allParams, 'header'),
                     requestBody: extractRequestBody(op),
-                    requestBodyDescription: body?.description,
-                    requestBodyRequired: body?.required,
+                    requestBodyDescription: body3?.description ?? body2?.description,
+                    requestBodyRequired: body3?.required ?? body2?.required,
                     responseSchema: extractResponseSchema(op),
                     responseDescription: extractResponseDescription(op),
                     errorResponses: extractErrorResponses(op),
@@ -184,20 +185,25 @@ function extractParams(params, location) {
     }));
 }
 function extractRequestBody(op) {
+    // OpenAPI 3.x: op.requestBody.content['application/json'].schema
     const body = op.requestBody;
-    if (!body)
-        return undefined;
-    const content = body.content;
-    if (!content)
-        return undefined;
-    // Prefer JSON
-    const jsonContent = content['application/json'];
-    if (jsonContent?.schema)
-        return jsonContent.schema;
-    // Fallback to first content type
-    const firstKey = Object.keys(content)[0];
-    if (firstKey && content[firstKey]?.schema) {
-        return content[firstKey].schema;
+    if (body) {
+        const content = body.content;
+        if (content) {
+            const jsonContent = content['application/json'];
+            if (jsonContent?.schema)
+                return jsonContent.schema;
+            const firstKey = Object.keys(content)[0];
+            if (firstKey && content[firstKey]?.schema) {
+                return content[firstKey].schema;
+            }
+        }
+    }
+    // Swagger 2.x: parameters[].in === 'body' → schema
+    if (op.parameters) {
+        const bodyParam = op.parameters.find((p) => p.in === 'body');
+        if (bodyParam?.schema)
+            return bodyParam.schema;
     }
     return undefined;
 }
@@ -221,24 +227,32 @@ function extractResponseSchema(op) {
         const resp = responses[code];
         if (!resp)
             continue;
+        // OpenAPI 3.x: resp.content['application/json'].schema
         const content = resp.content;
-        if (!content)
-            continue;
-        const jsonContent = content['application/json'];
-        if (jsonContent?.schema)
-            return jsonContent.schema;
-        const firstKey = Object.keys(content)[0];
-        if (firstKey && content[firstKey]?.schema) {
-            return content[firstKey].schema;
+        if (content) {
+            const jsonContent = content['application/json'];
+            if (jsonContent?.schema)
+                return jsonContent.schema;
+            const firstKey = Object.keys(content)[0];
+            if (firstKey && content[firstKey]?.schema) {
+                return content[firstKey].schema;
+            }
         }
+        // Swagger 2.x: resp.schema directly
+        if (resp.schema)
+            return resp.schema;
     }
     // Fallback: any 2xx
     for (const [code, resp] of Object.entries(responses)) {
-        if (code.startsWith('2') && resp.content) {
+        if (!code.startsWith('2'))
+            continue;
+        if (resp.content) {
             const jsonContent = resp.content['application/json'];
             if (jsonContent?.schema)
                 return jsonContent.schema;
         }
+        if (resp.schema)
+            return resp.schema;
     }
     return undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/openapi-parser",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "description": "OpenAPI spec parser and code generator for Pikku",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/codegen.ts

@@ -211,7 +211,10 @@ function generateFunctionFile(
   // Determine error imports needed
   const errorClasses = getErrorClassesForResponses(parsed.errorResponses)
 
-  lines.push("import { z } from 'zod'")
+  const needsZod = hasInput || !!parsed.responseSchema
+  if (needsZod) {
+    lines.push("import { z } from 'zod'")
+  }
   lines.push("import { pikkuSessionlessFunc } from '#pikku'")
 
   if (errorClasses.length > 0) {
@@ -246,8 +249,6 @@ function generateFunctionFile(
   if (hasInput) funcConfig.push(`  input: ${inputName},`)
   if (parsed.responseSchema) {
     funcConfig.push(`  output: ${outputName},`)
-  } else {
-    funcConfig.push('  output: z.void(),')
   }
 
   if (errorClasses.length > 0) {
@@ -303,10 +304,7 @@ function buildInputSchema(
         if (propSchema.readOnly) continue
         const isOptional = !requiredSet.has(key)
         const zodCode = schemaToZod(propSchema, ctx, { optional: isOptional })
-        const withDesc = propSchema.description
-          ? `${zodCode}.describe(${JSON.stringify(propSchema.description)})`
-          : zodCode
-        props.push(`  ${safeKey(key)}: ${withDesc},`)
+        props.push(`  ${safeKey(key)}: ${zodCode},`)
       }
     } else {
       const bodyZod = schemaToZod(parsed.requestBody, ctx)

package/src/parse-openapi.test.ts

@@ -1,6 +1,9 @@
 import { strict as assert } from 'assert'
 import { describe, test } from 'node:test'
-import { computeContractHash } from './parse-openapi.js'
+import { writeFile, rm, mkdtemp } from 'fs/promises'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { computeContractHash, parseOpenAPISpec } from './parse-openapi.js'
 import type { ParsedSpec } from './parse-openapi.js'
 
 function makeSpec(overrides: Partial<ParsedSpec> = {}): ParsedSpec {
@@ -148,3 +151,151 @@ describe('computeContractHash', () => {
     )
   })
 })
+
+describe('parseOpenAPISpec — Swagger 2.0', () => {
+  const swagger2Spec = {
+    swagger: '2.0',
+    info: { title: 'Test API', version: '1.0.0' },
+    host: 'api.example.com',
+    basePath: '/v1',
+    schemes: ['https'],
+    definitions: {
+      Pet: {
+        type: 'object',
+        required: ['name'],
+        properties: {
+          id: { type: 'integer', format: 'int64' },
+          name: { type: 'string' },
+          status: { type: 'string', enum: ['available', 'sold'], description: 'pet status' },
+        },
+      },
+    },
+    securityDefinitions: {
+      api_key: { type: 'apiKey', name: 'api_key', in: 'header' },
+    },
+    paths: {
+      '/pets': {
+        get: {
+          operationId: 'listPets',
+          summary: 'List all pets',
+          parameters: [
+            { in: 'query', name: 'status', type: 'string', description: 'Filter by status' },
+          ],
+          responses: {
+            '200': {
+              description: 'A list of pets',
+              schema: { type: 'array', items: { $ref: '#/definitions/Pet' } },
+            },
+          },
+        },
+        post: {
+          operationId: 'createPet',
+          summary: 'Create a pet',
+          parameters: [
+            {
+              in: 'body',
+              name: 'body',
+              description: 'Pet to create',
+              required: true,
+              schema: { $ref: '#/definitions/Pet' },
+            },
+          ],
+          responses: {
+            '201': {
+              description: 'Created',
+              schema: { $ref: '#/definitions/Pet' },
+            },
+            '400': { description: 'Bad request' },
+          },
+        },
+      },
+      '/pets/{petId}': {
+        get: {
+          operationId: 'getPet',
+          parameters: [
+            { in: 'path', name: 'petId', type: 'integer', required: true },
+          ],
+          responses: {
+            '200': {
+              description: 'A pet',
+              schema: { $ref: '#/definitions/Pet' },
+            },
+          },
+        },
+      },
+    },
+  }
+
+  let tmpDir: string
+  let specPath: string
+
+  test('setup', async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'openapi-test-'))
+    specPath = join(tmpDir, 'spec.json')
+    await writeFile(specPath, JSON.stringify(swagger2Spec))
+  })
+
+  test('extracts component schemas from definitions', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    assert.ok(spec.componentSchemas.Pet)
+    assert.equal(spec.componentSchemas.Pet.type, 'object')
+    assert.ok(spec.componentSchemas.Pet.properties?.name)
+  })
+
+  test('extracts server URLs from host/basePath/schemes', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    assert.deepEqual(spec.serverUrls, ['https://api.example.com/v1'])
+  })
+
+  test('detects apiKey auth from securityDefinitions', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    assert.equal(spec.authType, 'apiKey')
+  })
+
+  test('extracts requestBody from body parameter', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    const createPet = spec.operations.find(op => op.operationId === 'createPet')
+    assert.ok(createPet?.requestBody)
+    assert.equal(createPet.requestBody.type, 'object')
+    assert.ok(createPet.requestBody.properties?.name)
+    assert.equal(createPet.requestBodyRequired, true)
+    assert.equal(createPet.requestBodyDescription, 'Pet to create')
+  })
+
+  test('extracts responseSchema from Swagger 2.0 response', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    const createPet = spec.operations.find(op => op.operationId === 'createPet')
+    assert.ok(createPet?.responseSchema)
+    assert.equal(createPet.responseSchema.type, 'object')
+
+    const listPets = spec.operations.find(op => op.operationId === 'listPets')
+    assert.ok(listPets?.responseSchema)
+    assert.equal(listPets.responseSchema.type, 'array')
+  })
+
+  test('extracts query params', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    const listPets = spec.operations.find(op => op.operationId === 'listPets')
+    assert.equal(listPets?.queryParams.length, 1)
+    assert.equal(listPets?.queryParams[0].name, 'status')
+  })
+
+  test('extracts path params', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    const getPet = spec.operations.find(op => op.operationId === 'getPet')
+    assert.equal(getPet?.pathParams.length, 1)
+    assert.equal(getPet?.pathParams[0].name, 'petId')
+    assert.equal(getPet?.pathParams[0].required, true)
+  })
+
+  test('extracts error responses', async () => {
+    const spec = await parseOpenAPISpec(specPath)
+    const createPet = spec.operations.find(op => op.operationId === 'createPet')
+    assert.equal(createPet?.errorResponses.length, 1)
+    assert.equal(createPet?.errorResponses[0].statusCode, 400)
+  })
+
+  test('cleanup', async () => {
+    await rm(tmpDir, { recursive: true, force: true })
+  })
+})

package/src/parse-openapi.ts

@@ -106,12 +106,11 @@ export async function parseOpenAPISpec(filePath: string): Promise<ParsedSpec> {
   const securitySchemes = extractSecuritySchemes(doc)
   const tagDescriptions = extractTagDescriptions(doc)
 
-  // Extract component schemas
+  // Extract component schemas (OpenAPI 3.x: components.schemas, Swagger 2.x: definitions)
   const componentSchemas: Record<string, OpenAPISchema> = {}
-  if (doc.components?.schemas) {
-    for (const [name, schema] of Object.entries(doc.components.schemas)) {
-      componentSchemas[name] = schema as OpenAPISchema
-    }
+  const rawSchemas = doc.components?.schemas ?? doc.definitions ?? {}
+  for (const [name, schema] of Object.entries(rawSchemas)) {
+    componentSchemas[name] = schema as OpenAPISchema
   }
 
   // Extract operations (skip deprecated)
@@ -132,7 +131,9 @@ export async function parseOpenAPISpec(filePath: string): Promise<ParsedSpec> {
 
         const allParams: any[] = [...sharedParams, ...(op.parameters ?? [])]
 
-        const body = op.requestBody
+        // OpenAPI 3.x: op.requestBody, Swagger 2.x: parameters[].in === 'body'
+        const body3 = op.requestBody
+        const body2 = allParams.find((p: any) => p.in === 'body')
 
         operations.push({
           operationId: op.operationId,
@@ -145,8 +146,8 @@ export async function parseOpenAPISpec(filePath: string): Promise<ParsedSpec> {
           queryParams: extractParams(allParams, 'query'),
           headerParams: extractParams(allParams, 'header'),
           requestBody: extractRequestBody(op),
-          requestBodyDescription: body?.description,
-          requestBodyRequired: body?.required,
+          requestBodyDescription: body3?.description ?? body2?.description,
+          requestBodyRequired: body3?.required ?? body2?.required,
           responseSchema: extractResponseSchema(op),
           responseDescription: extractResponseDescription(op),
           errorResponses: extractErrorResponses(op),
@@ -266,20 +267,25 @@ function extractParams(
 }
 
 function extractRequestBody(op: any): OpenAPISchema | undefined {
+  // OpenAPI 3.x: op.requestBody.content['application/json'].schema
   const body = op.requestBody
-  if (!body) return undefined
-
-  const content = body.content
-  if (!content) return undefined
+  if (body) {
+    const content = body.content
+    if (content) {
+      const jsonContent = content['application/json']
+      if (jsonContent?.schema) return jsonContent.schema as OpenAPISchema
 
-  // Prefer JSON
-  const jsonContent = content['application/json']
-  if (jsonContent?.schema) return jsonContent.schema as OpenAPISchema
+      const firstKey = Object.keys(content)[0]
+      if (firstKey && content[firstKey]?.schema) {
+        return content[firstKey].schema as OpenAPISchema
+      }
+    }
+  }
 
-  // Fallback to first content type
-  const firstKey = Object.keys(content)[0]
-  if (firstKey && content[firstKey]?.schema) {
-    return content[firstKey].schema as OpenAPISchema
+  // Swagger 2.x: parameters[].in === 'body' → schema
+  if (op.parameters) {
+    const bodyParam = op.parameters.find((p: any) => p.in === 'body')
+    if (bodyParam?.schema) return bodyParam.schema as OpenAPISchema
   }
 
   return undefined
@@ -304,24 +310,30 @@ function extractResponseSchema(op: any): OpenAPISchema | undefined {
     const resp = responses[code]
     if (!resp) continue
 
+    // OpenAPI 3.x: resp.content['application/json'].schema
     const content = resp.content
-    if (!content) continue
-
-    const jsonContent = content['application/json']
-    if (jsonContent?.schema) return jsonContent.schema as OpenAPISchema
+    if (content) {
+      const jsonContent = content['application/json']
+      if (jsonContent?.schema) return jsonContent.schema as OpenAPISchema
 
-    const firstKey = Object.keys(content)[0]
-    if (firstKey && content[firstKey]?.schema) {
-      return content[firstKey].schema as OpenAPISchema
+      const firstKey = Object.keys(content)[0]
+      if (firstKey && content[firstKey]?.schema) {
+        return content[firstKey].schema as OpenAPISchema
+      }
     }
+
+    // Swagger 2.x: resp.schema directly
+    if (resp.schema) return resp.schema as OpenAPISchema
   }
 
   // Fallback: any 2xx
   for (const [code, resp] of Object.entries(responses) as [string, any][]) {
-    if (code.startsWith('2') && resp.content) {
+    if (!code.startsWith('2')) continue
+    if (resp.content) {
       const jsonContent = resp.content['application/json']
       if (jsonContent?.schema) return jsonContent.schema as OpenAPISchema
     }
+    if (resp.schema) return resp.schema as OpenAPISchema
   }
 
   return undefined