paths-well-formed
Since 0.9.0 · fixed by --fix · In the rulesets: Recommended at warning, Strict at error, All at error
This rule checks whether the paths of a Swagger 2.0 document are well-formed.
Rule details
Consistently formatted paths are easier to read and avoid surprises with
servers that treat /pets, /pets/ and /Pets as different resources.
The paths-well-formed rule reports Path is not well-formed <path> on every
path item whose path:
- does not start with a slash,
- contains empty segments (
//), - ends with a slash (except the root path
/), - contains upper-case ASCII letters outside template expressions.
Template expressions such as {petId} are left as they are, so parameter names
may use any case.
The OpenAPI linter has a rule of the same name, paths-well-formed, for OpenAPI 3.x documents.
Turn the rule off when the paths are dictated by an existing implementation that cannot be changed.
Examples
Good. The paths are well-formed.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
type: string
responses:
'200':
description: A single pet.
Bad. The path has an upper-case letter, an empty segment and a trailing slash.
swagger: '2.0'
info:
title: Pet Store
version: 1.0.0
paths:
/Pets//{petId}/:
get:
parameters:
- name: petId
in: path
required: true
type: string
responses:
'200':
description: A single pet.
Automatic fixes
--fix renames each malformed path to its
normalized form: a leading slash is added, empty segments and the trailing
slash are removed, and letters outside template expressions are lower-cased.
For example, /Pets//{petId}/ becomes /pets/{petId}.
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.
commands:
lint:
swagger:
rules:
paths-well-formed: off