Skip to content

feat(api): say how to turn off a linting rule when validation fails on one - #483

Open
mrafnadeem-apimatic wants to merge 1 commit into
devfrom
feat/configure-validation-hint
Open

mrafnadeem-apimatic wants to merge 1 commit into
devfrom
feat/configure-validation-hint

Conversation

@mrafnadeem-apimatic

Copy link
Copy Markdown
Contributor

Summary

A customer could not get their OpenAPI definition through apimatic api validate because of two linting rules that report at Error severity:

Message Ruleset Rule
No description found for enum item. openapi-v3-agentic-tools-linting required-description-for-enum-item
Empty enumeration item found which is not allowed. openapi-v3-apimatic-linting non-empty-schema-enum-value

Both can be turned off, or lowered to a warning, with ValidationConfiguration in APIMATIC-META.json, but nothing in the CLI says so. When linting fails, api validate and quickstart now link to Configure Validation and say where the file has to go:

  • A project's src/spec: beside the API definition.
  • --file, --url, or a file or URL given to quickstart: zipped together with the definition. A single file is uploaded on its own, so an APIMATIC-META.json next to it is never read. Checked on dev: --file openapi.yaml with the config beside it exits 1, and --file on a zip of the two exits 0.

api validate shows the line only when linting failed, because validation rules cannot be turned off. Quickstart's "How to fix" note always shows it, worded "If a linting rule doesn't fit your API", because quickstart does not say whether validation or linting failed.

api validate -i <project>:

●  If a linting rule doesn't fit your API, turn it off or lower its severity in an 'APIMATIC-META.json' beside your API definition:
│  https://docs.apimatic.io/v4/define-validate/validate-lint/configuring-validation
└  Failed

Quickstart, given a local file (box border trimmed):

■  Oops, it looks like there are some errors in your API Definition
│
◇  How to fix
│  Ask an AI coding agent to run this command and fix what it reports:
│  apimatic api validate --file=<path>
│
│  Or use APIMatic's interactive VS Code Extension:
│  https://marketplace.visualstudio.com/items?itemName=apimatic-developers.apimatic-for-vscode
│
│  If a linting rule doesn't fit your API, turn it off or lower its severity in an 'APIMATIC-META.json' zipped together with your API definition:
│  https://docs.apimatic.io/v4/define-validate/validate-lint/configuring-validation

Why sdk generate, plugin generate and portal generate are unchanged

On dev, the hint would point these commands at a setting that cannot fix their failures:

  • Linting does not stop them. sdk generate and portal generate exit 0 with both rules above failing, and with a Blocking linting rule failing (enum: []).
  • A CodeGen validation rule does stop them, for example apimatic-codegen-validation/atleast-one-endpoint. ValidationConfiguration cannot turn validation rules off, and with SkipCodeGenerationChecks: true both commands still fail with the same message.
  • plugin generate was not run, because it needs interactive setup first. It reports a failed generation through the same poller as sdk generate.

Testing

  • pnpm test passes. New tests:
    • ValidateAction shows the line when linting fails, not when only validation fails, and not when quickstart asks it to stay quiet.
    • ApiValidatePrompts.lintingFailed and quickstart's specValidationFailed use the right wording for each kind of spec.
  • Against dev, api validate:
    • A project failing lint shows the "beside" wording, and --file shows the "zipped" wording.
    • A project whose APIMATIC-META.json skips the failing rules succeeds with no hint.
  • Against dev, quickstart driven through psmux:
    • A local file and an adopted project each show their wording in "How to fix".
    • A zip whose APIMATIC-META.json skips the rules, and one that lowers them to Warning, both pass validation and reach step 3.

🤖 Generated with Claude Code

…n one

When linting fails, `api validate` and quickstart's "How to fix" note now
link to the Configure Validation docs and say where APIMATIC-META.json goes:
beside the definition in a project, or zipped with it for a file or URL,
which is uploaded on its own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant