duplicate-paths

YAML allows duplicate keys, but only keeps the last occurrence. When OpenAPI specifications contain duplicate path definitions, earlier path definitions are silently lost during parsing, leading to missing API endpoints without any warning.

This rule detects duplicate path keys at the raw YAML level before they’re processed by the OpenAPI parser, ensuring you don’t accidentally lose API endpoint definitions.

Why did this violation appear?

Your OpenAPI specification contains duplicate path definitions. While YAML parsing technically succeeds, only the last definition of each duplicated path is retained - all previous definitions are silently discarded.

What is this rule checking for?

The rule scans the raw YAML structure for duplicate keys under the paths section and reports each occurrence after the first one.

Bad example

openapi: 3.1.0
info:
  title: API with duplicate paths
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      # This definition will be lost!
  /users/{id}:
    post:
      summary: Create user
      # Only this definition will be kept

Good Example

openapi: 3.1.0
info:
  title: API with properly combined paths
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
    post:
      summary: Create user
    # All operations combined under one path definition

How do I fix this violation?

Combine all operations for each path under a single path definition. Each HTTP method (GET, POST, PUT, DELETE, etc.) should be defined as a separate operation under the same path key rather than duplicating the path itself.

Before bundling or processing your specification, ensure you run linting to catch these issues, as the bundler will silently drop the duplicate definitions just like any YAML parser would.