# paths-well-formed

Source: https://api-genie.dev/docs/linter/swagger/rules/paths-well-formed

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. 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](/docs/linter/openapi/rules/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.

```yaml
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.

```yaml
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}`.
