Validation Report Structure
After each validation/inspection action, you get one or more reports to see in the OpenAPI Inspector view. So, for instance, when validating a path you may get an aggregated report containing many subreports of that path operations, parameters, responses.., within each operation, and so on. All in one long but nicely structured report.
A report is a check unit with only one error, warning, or info category/severity. From top-down (see screenshot below), each report has:
- Category/Severity header,
- Title, (of the report)
- Description, (of the error, warning, or info)
- Cause location, if available (the place this error, warning, or info is located in the document)
- Solution/Remedy suggestion (to resolve the reported error, warning, or info).
- One or more links referencing some helpful pages related to the current report, such as the OpenAPI specs pages.
Please also note the links [Show in Schemas view, Show in Paths view and Show source code] that, when available, you may click to jump to the affected component.
An error in the report is either semantics-based when they're derived from infringements of the OpenAPI specs or structural when we encounter a document component whose definition would cause some errors later on. E.g, Schemas reference recursion errors that would cause loops when generating SDKs or tooling.
A validation error must be fixed to avoid deployment and code/toolings generations later on. If it's Specs-based, then the document is (partially) invalid.
Error report example:
Although a report warning is less urgent than an error one when it comes to fixing. Nevertheless, it's an indication of a bad design path. An example of this is overlooking operations id's by not defining any. Third-party generation tools, including, the ones our studio offers, may not like it.
Warning report example:
An info report indicates, at most, a best design/practice advice one might or might not follow. But it's always a good practice to follow good practices! Or isn't it! :-)
Info report example: