Prefer a spec file that is committed or fetched at a fixed commit. A live URL means the client you build today depends on whatever the server returns right now, which can change, be tampered with or go offline. Use a URL only when you control it and record what you fetched.
What the tool accepts
The generator's input option takes an OpenAPI spec as a URL or a file. There is also an auth option that adds authorization headers when fetching definitions remotely, passed as a URL encoded string of name and header pairs.
So fetching from a protected endpoint during a build is supported. That does not mean it is a good default.
Three problems with a live URL
Repeatability. Run the same job twice and you may get different clients because the spec changed between runs.
Integrity. If the URL serves over an unprotected channel, or the host is compromised, the spec can be altered. A changed spec can add operations, change server addresses or alter schemas, and the generator will faithfully write code for it.
Secrets in the pipeline. To reach a private spec the job needs credentials. Those then sit in CI variables and may appear in logs if command lines are echoed.
| Input choice | Repeatable | Reviewable | Needs credentials in CI |
|---|---|---|---|
| Spec file committed in the repo | Yes | Yes, in the pull request | No |
| URL at a fixed commit of a repository | Yes | Yes | Maybe |
| Live URL of a running service | No | No | Often |
A safer arrangement
- Make the spec a file in version control, owned by the team that owns the API.
- If the client lives in another repository, fetch the spec at a specific tag or commit hash and record that hash alongside the generated output.
- Validate the spec before generating. The CLI has a validate command with a recommend option that suggests improvements. Fail the build on errors.
- Avoid the skip validate spec flag in CI. It disables the default check, so a broken or odd spec flows straight into code.
- Review spec changes as carefully as code changes, especially server URLs, security schemes and added operations.
Why spec review is a security task
A client built from a spec trusts it completely. If the spec lists a different server address, the generated base URL changes. If a security scheme is dropped, the client stops sending credentials in the way you expect. Reviewing the spec diff is the cheapest place to catch that.
For writing specs that help later testing, see how to write an OpenAPI spec that helps security testing, and for detecting a spec that no longer matches the service, OpenAPI spec drift.
Where Safeguard fits
Safeguard includes API security scanning, which can test a running API against its description, and policy gates on pull requests where spec changes can be held for review.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how the scan works from an API description.
Quick check
Can the generator fetch a spec that needs authentication?
Yes, the documentation describes an auth option that adds headers when fetching definitions remotely. Weigh where the credential is stored before using it.
Is validating the spec enough to trust it?
No. Validation checks structure, not intent. A valid spec can still point at the wrong server.
Sources
Last reviewed: 19 October 2026.
