Validating OpenAPI Definitions for WSO2 API Manager 4.2.0 with swagger-linter_420

Photo by RealToughCandy.com: https://www.pexels.com/photo/person-holding-a-red-npm-sticker-11035482/

I recently developed and published an npm package, swagger-linter_420, designed to validate OpenAPI (formerly Swagger) definitions as per the requirements of WSO2 API Manager 4.2.0. This package provides a streamlined validation tool particularly beneficial for users migrating from earlier versions of the API Manager. It also helps ensure that the OpenAPI definitions of the user, meet the specifications required by WSO2 API Manager 4.2.0. You can access the package here: swagger-linter_420 on npm.

Validation Layers

The swagger-linter_420 package incorporates two validation layers to ensure compatibility:

1. API Manager Backend Validation:

• This layer includes a Java client embedded within the tool that mirrors the backend validation performed by WSO2 API Manager 4.2.0.
• If the definition fails this validation, it won’t be accepted by the API Manager, meaning the package will also reject it to maintain consistency.

2. Swagger Linter Validation:

• This layer behaves similarly to WSO2 API Manager’s frontend validation, using a spectral linter to scan the OpenAPI definition for errors.
• In API Manager’s implementation, while errors and warnings here are displayed, they won’t block the API creation.
• Hence the tool will display the errors in the same way without failing the validation based on the errors or warnings encountered in this level.

Validation Levels

This package offers two validation levels based on WSO2 API Manager’s settings. In both levels, linter validation behaves the same; it differs based on the backend validation, specifically its relaxedValidation option:

• Level 1: API Manager with relaxedValidation enabled.
• Level 2: Default validation by the API Manager.

Input Types

Users can provide a specific OpenAPI definition file (either JSON or YAML format) or an entire directory of OpenAPI definitions for batch validation.

Command Template

To run the validation, use the following command template:

swagger-linter_420 -f [path to API definition File or API definitions Directory] -l [validation level 1 or 2]

How to use

Note: Ensure you’re using Node version 16.

1. Download the npm package

npm i swagger-linter_420

2. Link the package

npm link swagger-linter_420

3. Set up your OpenAPI definition: Assume you have a file called petsAPI.json in ~/Downloads/apis.

Open a terminal and go inside the directory

cd ~Downloads/apis

4. Run validation: To validate using the default Level 2 setting of API Manager, use the following format :

swagger-linter_420 -f [path to API definition File or API definitions Directory] -l 2

• For a single file :

swagger-linter_420 -f /petsAPI.json -l 2

or

• For a directory of files:

swagger-linter_420 -d /petsAPI.json -l 2

Understanding Sample Output

Valid Definition

When an OpenAPI definition passes validation, the output indicates success, displaying a “Validation Passed” message.

Valid OpenAPI definition output. Image by Rusiri Illesinghe

Invalid Definition

An invalid definition presents two sections:

1. API Manager Backend Validation Results:

• This section checks against WSO2 API Manager’s backend logic. If the definition is invalid for API Manager 4.2.0, you’ll see the message:

"API Manager 4.2.0 will NOT ACCEPT this API definition."

2. Linter Validation Results:

• Any errors or warnings identified by the spectral linter appear here, although they won’t affect the definition’s acceptance by the API Manager if backend validation passes.

Invalid OpenAPI definition output. Image by Rusiri Illesinghe

With swagger-linter_420, you can now easily validate OpenAPI definitions, ensuring compatibility with WSO2 API Manager 4.2.0 and simplifying your API migration or setup processes.