OAS:OpenAPI Editor/Validation Report Structure

From Remain Software

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.

Report sections

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.

Openapi validation report structure.png

Error report

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:

Openapi validation report error.png

Warning report

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:

Openapi validation report warning.png


Info report

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:

Openapi validation validation info.png