Run the generator's validate command on the spec as the first CI step, fail the job on errors, and read the recommendations. Then add your own checks for the things validation cannot judge, such as server addresses and security schemes. Do this before any code is generated.
What the validate command does
The usage page documents a validate command that takes the spec as a URL or file and an optional recommend flag. For a valid spec it reports that no validation issues were detected. For an invalid one it lists the problems. The docs also show a generate option that skips validation and another that controls how strictly the MUST and SHALL wording of the OpenAPI specification is applied.
Steps
- Validate. Run the command against the committed spec. A non zero result should fail the job.
openapi-generator-cli validate -i openapi.yaml --recommend
- Keep validation on in generate. Do not set the skip validation flag in CI. If a legacy spec needs it, record why and set a date to fix the spec.
- Read recommendations. They can point to missing operation ids or odd constructs that lead to poor generated names or types.
- Check intent with simple rules. Write a short script or use a spec linter you already trust to assert:
- the list of server URLs matches an approved list
- each operation that needs authentication references a security scheme
- no example contains values that look like real tokens
- Diff the spec. Show a readable diff of paths, servers and security schemes in the pull request.
- Then generate, and compare with committed output as in commit or generate at build time.
What each check catches
| Check | Catches |
|---|---|
| Validate command | Structural errors and spec rule violations |
| Recommendations | Quality issues that affect generated code |
| Server URL allow list | A changed or injected base address |
| Security scheme assertion | Operations that lose authentication |
| Example scan | Tokens or internal names pasted into samples |
| Spec diff review | Added operations nobody expected |
Limits
Validation is about form. It cannot tell whether the spec matches the running service. For that, see OpenAPI spec drift, and for fetching the spec safely see remote spec URL or pinned file.
Where Safeguard fits
Safeguard includes API security scanning for running APIs and policy gates on pull requests, so spec and config changes can be held for review before code is generated from them.
Try it yourself
Click through it at your own pace, or open it full screen. Look at what an API focused scan reports.
Quick check
Does a passing validate result mean the spec is correct?
It means the document is well formed. It does not mean the content is right.
Is it okay to skip validation for an old spec?
Only as a temporary, recorded exception. Fix the spec and turn validation back on.
Sources
Last reviewed: 19 October 2026.
