How to validate Open API Files effectively with WSO2 API Manager

OpenAPI Specification (OAS) is a key aspect of API-first design. So keeping accurate and quality OpenAPI files is crucial for a sustainable API development practice. In this article, we discuss different aspects of OpenAPI file validation and tools that can be used for that. We mainly focus on WSO2 API Manager 4.2.0 which now has an inbuilt method to validate OpenAPI files without having to use any external tools. In addition to standard OAS rules, we also discuss how to write your own validation rules to validate your OpenAPI files so you can have your API definitions adhere to your organisation’s standards and policies. At the end, we also cover some typical OpenAPI validation requirements with some example custom rules. I believe this article will add some valuable additions to your API development practices.

Significance of OpenAPI Specification (OAS) in API-first Design

OpenAPI Specification (OAS) is a description format for REST APIs and webhooks. It was formerly known as Swagger. It allows us to describe entire APIs including available endpoints/operations, input/output parameters, authentication methods, and so on. Therefore, when OAS is used in API development, maintaining the accuracy and quality of OpenAPI files is crucial because the entire API development lifecycle depends on it. So, there should be some good and easy way to validate these OpenAPI files.

Steps to validating Open API Files

When it comes to OAS validation, there are 2 aspects to it, in terms of what you want to validate.

1. Open API files must be validated against standard OAS rules.
2. Open API files can also be validated against custom rules, for example, your organization-specific rules.

Standard OAS Rules: Ensuring Precision in Open API Files

This is an important step to ensure that Open API files are accurate, adhere to the best practices, and follow the established OAS standards. There are tools available to validate OpenAPI files against OpenAPI Specification. Spectral and Swagger-Editor are two such popular tools.

Here are some important OAS rules typically validated under this category.

• File format syntax validation
  • Ensure the Open API file has the correct JSON/YAML formatting and no syntax errors.
• Schema Validation
  • Verification of the correctness of schema structures
  • Data types and object properties are declared within the OpenAPI specification.
• Parameter Validation
  • Ensure the query parameters, path parameters, headers, and cookies are correctly defined with data types, descriptions, and validations.
• Ambiguous API resources
  • Ensure there are no conflicting API resources, for example, `/pets/{name}` and `/pets/{id}`.
• Security Definitions:
  • Verifying the accuracy and completeness of security definitions
• Successful API responses
  • Ensure each API resource has at least one successful response (2xx or 3xx)
• Versioning and Compatibility
  • Ensuring that the API definition complies with a specific version of the OpenAPI Specification and maintains backwards or forward compatibility.
• Error Handling
  • Validation of error responses, status codes, and error message structures defined within the API specification.
• API Examples
  • Ensure the given API request/response payload examples are valid as per the API definition

Until you validate your OpenAPI files against all these standard rules, and make them error-free, they are not real OpenAPI files, but just text files. So, by using an OpenAPI validation tool to validate these standard rules, you can catch inconsistencies at the early stages of the API development cycle and make them actual and accurate OpenAPI files before you use those to build real APIs. 

Crafting consistency: Custom Linter Rules for Open API Validation

Organizations and development teams usually have their own standards in addition to industry standards. That holds for the APIs as well. When an organization wants to publish APIs, they may want to ensure that API developers adhere to certain rules that are based on their organisation’s internal standards and policies. For example, API path and parameters naming conventions, availability of API examples, certain restrictions for API information, etc. To facilitate such requirements, custom linter rules can be used to validate OpenAPI files. However, not all OpenAPI validation tools support custom linter rules. Spectral is one those great tools that supports both standard OAS rules and custom linter rules.

Leveraging WSO2 API Manager for Open API Files

If you’re a user of WSO2 API Manager, you’re lucky enough to have the full functionality of the Spectral linter tool inside WSO2 API Manager, and now you don’t have to worry about using an external tool anymore just to validate OpenAPI files. Since version 4.2.0, Spectral has been embedded into WSO2 API Manager with some additional UI support as well.

Now, when you import an OpenAPI file to WSO2 API Manager, it by default validates the file against standard OAS rules and shows you a summary of errors, warnings, information, and hints as shown below.

You can expand the `Linter Results` section and read more details about each error/warning etc.

At this point, you have 2 options.

1. Update the original OpenAPI file and re-import to create the API.
2. Proceed to create the API with the current OpenAPI file and modify the API later to fix the errors.

Option 2 could be a suitable choice if you are unable to update the original OpenAPI file for some reason, for example, if you’re not the owner of it. On the other hand, it doesn’t break your API creation flow. It just lets you continue with it. If you pick this option, you can fix the linter errors after creating the API. For that, you should go to the `API Definition` section and then `Edit` the API definition. 

Then if you switch to the “Linter” view on the right, you can see the errors and warnings detected by Spectral. When you fix errors/warnings on the left pane, the relevant error/warning message on the right goes away. 

Once you are happy with the output, you can save the API definition and proceed with the rest of your API lifecycle.

Configuring Custom Linter Rules in WSO2 API Manager

As discussed earlier, one of the most powerful features of Spectral is the ability to define custom rules. You can do that too within the WSO2 API Manager. It provides you with some additional UIs to make this process smooth. Here is how to add a new custom rule.

1. Go to the admin portal. On the Left side panel, Click on Advanced under Settings. Then you will be redirected to the “Advanced Configurations” editor.

2. Here, you have to add a new key “LinterCustomRules” to this configuration file. (The default configuration does not have a “LinterCustomRules” section.)  Inside the “LinterCustomRules” section, add a new key “rules” as shown in the below image.

3. Inside this section, you can define any number of custom rules with custom rule keys. Here is an example rule that validates if the API’s contact email is a Yenlo email. (We will talk more about this rule in the next section)

4. After saving the above rule, if you have any new errors identified by the new rule, you will see them in the `API definition` section of the Publisher portal like this.

Exploring advanced Custom Linter Rules for Open API Validation

A custom linter rule has several parts. Let’s see what each of them means.

• Description: This describes the rule.
• Given: This specifies which part of the OpenAPI file that we want to validate.
• Then: This specifies how it should be validated. In this section, we can specify what should be validated using which function. We can also specify more function options here.
• Severity: This can be one of error, warn, info, hint, and off. This specifies the severity of the error.
• Message: This is an optional message to be shown with detected errors.

You can read more about these options in the Spectral official documentation.

Illustrative examples of custom rules for Open API Validation

Now let’s have a look at a few custom rules that can be useful in a typical API development process.

1. Let’s start with the email example we talked about earlier.

"company-info-email-rule": {
    "description": "Contact email address must be a Yenlo email.",
    "given": "$",
    "severity": "error",
    "then": {
        "field": "info.contact.email",
        "function": "pattern",
        "functionOptions": {
            "match": "^[a-z]+@yenlo.com$"
        }
    }
 }

This rule defines that the contact email of the info section must adhere to the `^[a-z]+@yenlo.com$` regex, which means it has to be a Yenlo email. Here it uses the “pattern” function with the “match” option.

2. All POST API resources should have an example request.

"post-request-example": {
    "description": "All POST application/json requests must have examples.",
    "given": "$.paths.*.post.requestBody.content.application/json",
    "severity": "error",
    "then": {
        "field": "examples",
        "function": "truthy"
    }
 }

This rule defines that if there are any POST request bodies with application/json content-type, they should have an example defined. Here, the function “truthy” means something (the field “examples” in this case) must exist. The opposite function of this is the “falsy” function which ensures something does not exist.

3. All schema properties must be in camelcase.

"model-properties-camelcase": {
    "description": "All schema properties must be in camelCase.",
    "given": "$.components.schemas.*.*.~",
    "severity": "warn",
    "then": {
        "function": "casing",
        "functionOptions": {
           "type": "camel"
        }
    }
 }

This rule uses the “casing” function with its option “type”. Spectral supports the following “cases” out of the box.

• camel (eg: veryLongName)
• pascal (eg: VeryLongName)
• kebab (eg: very-long-name)
• cobol (eg: VERY-LONG-NAME)
• snake (eg: very_long_name)
• macro (eg: VERY_LONG_NAME)

4. All tags must be sorted in alphabetical order.

"openapi-tags-alphabetical": {
    "description": "OpenAPI objects should have tags in the alphabetical order.",
    "given": "$",
    "severity": "warnn",
    "then": {
        "field": "tags",
        "function": "alphabetical",
        "functionOptions": {
           "keyedBy": "name"
        }
    }
 }

Here, the rule uses the “alphabetical” function that ensures a given array elements or object properties are sorted in the alphabetical order by a key given by the “keyedBy” option.

5. Tags should only come from a pre-defined list.

"whitelisted-tags": {
    "description": "Tags should be coming from the given list of tags.",
    "given": "$.paths.*",
    "severity": "error",
    "then": {
        "field": "tags",
        "function": "enumeration",
        "functionOptions": {
            "values": [
                "users",
                "articles",
                "categories"
            ]
        }
    }
 }

This rules uses the “enumeration” function which can be used to restrict a value to always be one of the given values.

6. All operations must have at least 1 tag but no more than 3.

"operation-singular-tag": {
    "description": "Operations must have between 1 and 3 types.",
    "given": "$.paths.*",
    "severity": "error",
    "then": {
        "field": "tags",
        "function": "length",
        "functionOptions": {
            "max": 3,
            "min": 1
        }
    }
 }

This rule uses the “length” function which has min and max options.

So, similarly, you can define more complex custom rules using different spectral core functions. You can read more about those here.

Building a sustainable API Development Practice

In this article, we discussed what is OpenAPI Specification and why we need it. We discussed the 2 aspects of OpenAPI validation and how tools support those. We specifically talked about Spectral which is now integrated with WSO2 API Manager, and how you can use it to validate your OpenAPI files against standard OAS rules and custom linter rules as well.  We delved more extensively into custom rules and covered some typical validation use cases with example custom rules. So, if you’re an API developer, an API product owner, or anyone who works in the API development space, I believe what we discussed in this article might be useful for you to maintain a sustainable API development practice in your organization.