Validation Report Structure[edit]
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.
Report sections[edit]
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.
Error report[edit]
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:
Warning report[edit]
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:
Info report[edit]
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:
