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

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?