Linter rulesSwagger 2.0paths-well-formed

paths-well-formed

Since 0.9.0 · fixed by --fix

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.

Configuration

None.

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

When invoked with --fix, this rule 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}.

When Not to Use It

You may disable this rule when the paths are dictated by an existing implementation that cannot be changed.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading