Define & Validate APIsValidation RulesetsOpenAPI Rulesets
Swagger v2 Syntax Validation
Validation checks performed on provided Swagger v2 file to check its conformance to Swagger 2.n syntax rules.
| Property | Value |
|---|---|
| Ruleset ID | swagger-v2-syntax-validation |
| Code prefix | SWAGGER20SYNTAX_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Syntax |
| Rules | 11 |
API Server
| Code | Rule | Severity | What it checks |
|---|---|---|---|
SWAGGER20SYNTAX_V001 | no-host-path-templating | Error | In Swagger 2.0, the host field is used to specify the hostname (and optionally the port number) where the API is hosted. The violation occurs when path templating, which is the use of variables within the host field, is detected. Path templating is not supported in the host field according to the Swagger 2.0 specification. |
SWAGGER20SYNTAX_V002 | base-path-starts-with-leading-slash | Error | In Swagger 2.0, the basePath field is used to specify the common path prefix for all API endpoints. The violation occurs when the basePath value does not begin with a leading slash (/), which is required according to the Swagger 2.0 specification. |
SWAGGER20SYNTAX_V003 | no-base-path-templating | Error | In Swagger 2.0, the basePath field is used to specify the common path prefix for all API endpoints. This violation occurs when path templating, which involves using variables within the basePath field, is detected. Path templating is not supported in the basePath field according to the Swagger 2.0 specification. |
Paths
| Code | Rule | Severity | What it checks |
|---|---|---|---|
SWAGGER20SYNTAX_V020 | path-name-begin-with-forward-slash | Error | In Swagger 2.0, each path within the paths section should start with a leading slash (/). This violation occurs when a path name is defined without the required leading slash, which is mandatory according to the Swagger 2.0 specification. |
Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
SWAGGER20SYNTAX_V040 | valid-response-http-status-code | Error | The Responses Object key must be a valid HTTP status code or set to 'default'. The key must be enclosed in quotation marks for compatibility between JSON and YAML. If the key is an explicit status code, then it must be valid according to RFC7231 and possibly listed in the registered status codes in the IANA Status Code Registry. |
References
| Code | Rule | Severity | What it checks |
|---|---|---|---|
SWAGGER20SYNTAX_V060 | valid-dollar-ref-path | Error | The '$ref' values must be RFC3986-compliant percent-encoded URIs. |
Specification Extensions
| Code | Rule | Severity | What it checks |
|---|---|---|---|
SWAGGER20SYNTAX_V080 | specification-extension-name-being-with-x-dash | Error | If any additional property needs to be added in the Swagger specification that is otherwise not part of the actual standard, specification extension can be used for this purpose at certain points. The extension name must begin with x- (e.g. x-internal-id). |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
SWAGGER20SYNTAX_V100 | valid-mime-type | Error | The mime type definitions should be in compliance with RFC6838. |
SWAGGER20SYNTAX_V101 | valid-url-format | Error | String value should be in the format of a proper URL. The URL path can be relative only if a server URL exists in the API document to help resolve the URL path into an absolute path. |
SWAGGER20SYNTAX_V102 | valid-email-address | Error | String value must be in the format of an email. |
SWAGGER20SYNTAX_V103 | valid-property-value-type | Error | Value of a Swagger standard property must be in accordance with the type set by the standard for that property. |
Learn more
OpenAPI v3 Standard Validation
Validation checks performed on provided OpenAPI v3 file to check its conformance to rules set by the OpenAPI v3 official standards document.
Swagger v2 Standard Validation
Validation checks performed on provided Swagger v2 file to check its conformance to rules set by the Swagger v2 official standards document.