feat: Add remote URL support for input specifications with authentication

[jonaslagoni]

Summary

Add support for loading AsyncAPI, OpenAPI, and JSON Schema specifications from remote URLs (HTTP/HTTPS) with optional authentication headers.

Current Behavior

All input processors only support local file paths:

• src/codegen/inputs/asyncapi/parser.ts:29 - uses fromFile()
• src/codegen/inputs/openapi/parser.ts:24 - uses readFileSync()
• src/codegen/inputs/jsonschema/parser.ts:72 - uses readFileSync()

Passing a URL like https://api.example.com/spec.yaml results in file system errors.

Proposed Behavior

URL Detection

Automatically detect URLs in inputPath:

// codegen.config.mjs
export default {
  inputType: 'asyncapi',
  inputPath: 'https://raw.githubusercontent.com/org/repo/main/asyncapi.yaml',
  // ...
};

Authentication Support

Support common auth patterns for secure specifications:

export default {
  inputType: 'openapi',
  inputPath: 'https://api.internal.company.com/openapi.json',
  
  // Option 1: Bearer token
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN
  },
  
  // Option 2: API Key header
  auth: {
    type: 'apiKey',
    header: 'X-API-Key',
    value: process.env.API_KEY
  },
  
  // Option 3: Custom headers
  auth: {
    type: 'custom',
    headers: {
      'Authorization': `Bearer ${process.env.TOKEN}`,
      'X-Tenant-ID': 'acme-corp'
    }
  }
};

Implementation Notes

URL Detection

function isRemoteUrl(path: string): boolean {
  return path.startsWith('http://') || path.startsWith('https://');
}

Fetching

• Use fetch or node-fetch for HTTP requests
• Support timeout configuration
• Handle redirects
• Cache responses (optional, for watch mode)

Error Handling

• Network errors (timeout, connection refused)
• Auth errors (401, 403)
• Not found (404)
• Rate limiting (429)

Acceptance Criteria

• AsyncAPI processor supports remote URLs
• OpenAPI processor supports remote URLs
• JSON Schema processor supports remote URLs
• Bearer token authentication works
• API key authentication works
• Custom headers authentication works
• Environment variables work in auth config
• Helpful error messages for auth failures
• Documentation updated

Related

• Prerequisite for EventCatalog integration (services may reference remote specs)
• Similar to how EventCatalog generators support remote URLs

[jonaslagoni]

🎉 This issue has been resolved in version 0.72.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀