Validation

This section is about validating/inspecting your OpenAPI document components such as schemas, paths, operation, and so on. The validation result report is shown in the OpenAPI Inspector view so that you can fix the resulting errors, warnings, if any, and improve your OpenAPI document.

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.

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:

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:

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:

Automatic validation

OpenAPI studio will run automatically an initial validation once when you open your OpenAPI document. If something to report is found, then the tabs at the bottom of the OpenAPI studio (Start, Schemas, Paths, and so on...) will be marked with an error, warning, or info icon indicating that. Click a marked tab to activate and see its report in the OpenAPI Inspector view.

Please note that the Start tab (at the bottom-left) is the one initially selected and its report is therefore automatically shown in the OpenAPI Inspector view.

Validate Document Info

Use the button from the local toolbar (atop) to validate the document info (aka, Info Object by OpenAPI Specs) located in the first tab named Start within the Remain API Studio bottom tabs.

Please note that this info Start tab will be automatically validated the first time you open a document.

You get to see the validation report in the Inspector View

Validate Schemas

To validate/inspect schemas select, first, the Schemas tab at the bottom of the OpenAPI studio.

Validate All Schemas

To validate/inspect all document schemas in one go, select the root node Schemas, then either:

• Right-click it and select Validate All Schemas from the context menu.
• Or click the validation button from the view local toolbar.

Please note that this Schemas tab will be automatically validated the first time you open a document.

You get to see the validation report in the Inspector View

Validate Selected Schemas

Select the schemas you want to validate/inspect then, then either:

• Right-click it and select Validate from the context menu.
• Or click the validation button from the view local toolbar

Validate Paths

To validate/inspect paths select, first, the Paths tab at the bottom of the OpenAPI studio.

Please note that a path validation will also validate all its operations then drill down validating the operation parameters, responses, request-body, and so on.

Validate All Paths

To validate/inspect all document paths in one go, select the root node Paths, then either:

• Right-click it and select Validate All Paths from the context menu.
• Or click the validation button from the view local toolbar.

Please note that this Paths tab will be automatically validated the first time you open a document.

You get to see the validation report in the Inspector View

Validate Selected Paths

Select the path you want to validate/inspect then, then either:

• Right-click it and select Validate from the context menu.
• Or click the validation button from the view local toolbar

Validate Operations

To validate/inspect an operation select, first, the Paths tab at the bottom of the OpenAPI studio.

Select the operation you want to validate/inspect then, either:

• Right-click it and select Validate from the context menu.
• Or click the validation button from the view local toolbar

You get the validation report to see in the OpenAPI Inspector view.

Please note that an operation validation will drill down validating all its parameters, request-body, responses and so on.

Validate Parameters

To validate/inspect global parameters or those belonging to a given operation, select, first, the Paths tab at the bottom of the OpenAPI studio.

Select the operation whose parameters you want to validate/inspect then click the validation button from the local toolbar of the parameters tab. This action will validate all parameters including the global ones defined in the Global Parameters tab

To validate global parameters only, operation selection is not needed.

Validate Request-bodies

To validate/inspect global Request-bodies or the one belonging to a given operation, select, first, the Paths tab at the bottom of the OpenAPI studio.

Select the operation whose Request-body you want to validate/inspect then click the validation button from the local toolbar of the Request Bodies tab. This action will validate all request-bodies including the global ones defined in the Global Request Bodies tab.

To validate global request-bodies only, operation selection is not needed.

Validate Responses

To validate/inspect global responses or the ones belonging to a given operation, select, first, the Paths tab at the bottom of the OpenAPI studio.

Select the operation whose responses you want to validate/inspect then click the validation button from the local toolbar of the Responses tab. This action will validate all responses including the global ones defined in the Global Responses tab.

To validate global responses only, operation selection is not needed.