As part of our efforts to improve existing format-specific validation, we are now introducing validators for Swagger v2.0 and OpenAPI v3.0 specifications.
Previous Status of Validation
Previously, we were only utilizing flexible format-specific validation approach, which did not encompass all standard checks. Our primary focus was to make the best possible attempt to import or transform a specification even in the presence of issues, except for those that completely blocked the process.
Furthermore, the validation messages that we provided offered minimal metadata pertaining to the actual issues, making it occasionally arduous to resolve the problems within the specification.
We also lacked the capability to configure the linting checks within our validation system.
Introducing Stricter Validation and Enhanced Linting
We are now announcing the support for format-specific stricter validation and enhanced linting in APIMatic, where your specifications get scrutinized by our new validators according to the standards defined by the respective format. This provides you with a detailed summary of the issues, including all the metadata needed to resolve an issue, such as the message itself that lets you know about the violation, the line number where the issue exactly occurred in the spec, the hints that help you think about possible ways to fix the issue and many more.
Using the Newer Validation
To enable the new stricter form of validation, we have introduced a new import setting called UseStrictValidation. This setting can be enabled by importing a metadata file along with the specification, with the UseStrictValidation import setting enabled.
Here's an example metadata file with the UseStrictValidation setting enabled:
{
"ImportSettings": {
"UseStrictValidation": true
}
}
OpenAPI v3.0 Standards
The OpenAPI v3.0 standards define a set of rules that must be adhered to by an OpenAPI specification, using reserved keywords such as MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT. These reserved keywords are employed to define certain rules that are mandatory for an OpenAPI spec to be valid, and these rules are referred to as standard validation rules.
Our new validation uses the concept of rulesets, where each ruleset is a group of rules with similar characteristics. The OpenAPI 3.0 standard validation rules have been segregated into 2 validation rulesets:
In addition to the mandatory rules, there are some rules that are considered good to have for an OpenAPI spec. These rules, referred to as standard linting rules, are defined using the reserved keywords such as SHOULD, SHOULD NOT, RECOMMENDED, and NOT RECOMMENDED.
The standard linting rules have been segregated into two linting rulesets:
Our new format-specific validation incorporates all the standard validation and linting rules defined in the official OpenAPI standard documentation.
Validation Example
"/api/path": {
"get": {
"summary": "Sample API with a path",
"description": "A sample API with a path URL that contains no templates.",
"operationId": "SampleAPI",
"parameters": [
{
"name": "pathParam",
"in": "path",
"description": "The path parameter.",
}
]
}
}
In the above example, we have an unused path parameter since there is no template expression in the path URL. According to the OpenAPI v3.0 standard document,
If
inis"path", the name field MUST correspond to a template expression occurring within the path field in the Paths Object.
So, the newer validation will log this as a violation:
Furthermore, when you click on the provided link within the validation message, it will direct you to a page that provides comprehensive details regarding the specific violated rule. This allows for easy access to in-depth information related to the rule that was flagged during the validation process. Follow this link for more details.
We are working towards format-specific strict validation for OpenAPI v3.1 standards as well and will be announcing their support in the near future.
Linting OpenAPI v3 Beyond Standards for Better API Consumption
While the OpenAPI v3.0 standard document tells you exactly what you need to do to ensure your OpenAPI v3.0 specification is compliant with the standards, if you need to increase your API consumption using the auto-generated SDKs and the developer experience portal, linting plays an important role. It guarantees that the generated SDK and Developer Portal offer all the necessary components to facilitate seamless API consumption.
In order to facilitate linting of the OpenAPI specification for Code and Docs Generation purposes, we have established our own set of rules. These rules ensure that the API specification provided for Code Generation meets the requirements for generating high-quality SDKs as well as producing comprehensive documentation. By adhering to these rules, we ensure that the generated SDKs and documentation are of the highest standard and effectively support developers in utilizing the API.
Here are a few examples of these rules in action:
- Very long titles, names, and summaries, which exceed 50 characters, can disrupt the user-friendliness of the generated Developer Portal. Subsequently, this can also lead to issues in the code generation process for SDKs. The following example illustrates this scenario:
"info": {
"title": "This is a very long info title which exceeds the limit of 50 characters.",
}
- Another scenario is of missing examples for parameters, media types, or schemas. In addition to demonstrating the intended payload that an object is expected to accept, we use these examples for automatic generation of test cases for the API. So, it is essential for example(s) to be defined using the example or examples property.
"parameters": [
{
"name": "language",
"in": "query",
"required": false,
"type": "string"
}
]
Code Generation Rulesets
- OpenAPI v3 Linting for APIMatic Code Generation
- OpenAPI v3 Syntax Linting for APIMatic Code Generation
Docs Generation Rulesets
- OpenAPI v3 Linting for APIMatic Portal Generation
- OpenAPI v3 Syntax Linting for APIMatic Portal Generation
For more detailed information on following best practices when creating your OpenAPI v3.0 specifications to improve API consumption, we invite you to read our blog post 14 Best Practices to Write OpenAPI for Better API Consumption.
Swagger v2.0 Standards
Despite the introduction of OpenAPI v3.0 and more recently, OpenAPI v3.1, there is still a need to cover all the validation checks for older versions as well. Swagger v2.0 is a format that is still used by many worldwide. So, we have added support for Swagger v2.0 standard rules as part of our format-specific stricter validation.
These cover all the mandatory validation checks from the Swagger v2.0 standard document, marked with keywords such as:
- “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”.
The Swagger v2.0 standard validation rulesets are available here.
Validating APIMatic Metadata files
Apart from OpenAPI v3.0, Swagger v2.0 validation, and linting, we have also introduced APIMatic Metadata file validation. Writing metadata files is now easier than ever for our users. Common syntax and semantic issues are now a thing of the past as the new metadata file validation aims to highlight such errors in the metadata file uploaded along with the API specification file. Further information about APIMatic Metadata files can be found here.
Metadata File Validation Ruleset
Please find the validation rulesets for metadata file here.
Support for Custom Rules Beyond Built-in Rulesets
Beyond APIMatic built-in rulesets, users can also define their own customized rulesets. Their specs would then be validated against the built-in rulesets plus the rulesets defined by them.
Custom rulesets can be defined in a file and referenced in the metadata file. Please refer to the official documentation on how to define your own custom rulesets.
In order to avoid any mistakes in defining custom rulesets, a few rules are in place to ensure that the custom rulesets have all the relevant information needed. Some of these rules are described below:
- Required Custom Rule Id: This rule helps ensure that the rules specified in the custom ruleset have rule "id" defined that is used as a unique identifier for the rule.
- Unique Custom Rule Id: To uniquely identify each rule. This rule is in place to prevent any rules from being introduced with a duplicate "id" property.
- Required Custom Rule Targets: The property ‘targets’ must be specified when defining a custom rule. This helps identify the target component(s) that need to be validated.
Custom Rulesets Validation Ruleset
Please refer to this document to learn more about the validation rulesets that are set in place for defining custom rulesets.
Link Custom Ruleset through Metadata File
To link a custom ruleset file through the metadata file, see the following example:
{
"Id": "my-custom-ruleset",
"Rules": [
{
"Id": "max-operation-id-length-30",
"VerificationMethod": "Length",
"Targets": [
{
"JsonPath": "$.paths.*.*.operationId"
}
],
"VerificationMethodArgs": {
"Maximum": 30
},
"Message": "Operation id is too long."
}
]
}
{
"ValidationConfiguration": {
"Rulesets": {
"my-custom-ruleset": {
"FilePath": "/path/to/ruleset/file"
}
}
}
}
Ability to Configure Validation
Both validation and linting are configurable, however, there are a greater number of configurable options for linting than there are for validation.
For instance, in the case of validation configurations, we can enable either a specific set of rules that are disabled by default or all of them. Whereas in the case of linting, we have the options to enable only a set of rules, skip a set of rules, configure the severity of rules, and skip rulesets altogether.
The following example shows how to configure linting using configuration:
{
"Rulesets": {
"openapi-v3-standards-linting": {
"Severity": "Information",
"Rules": {
"Skip": ["no-ambiguous-path"]
}
}
}
}
For further details on configuring linting and validation, visit the relevant documentation.
Visit www.apimatic.io or contact us for more information.