OAI / OAI/OpenAPI-Specification

More example `same hierarchy` in path templating

Open
#2,015 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification examples request matching
Dominant language
Markdown
Stars
31.2k
Forks
9.2k
Avg merge
6h 37m
Merged PRs (30d)
27

Description

We can't describe different templated name with same hierarchy.

Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical.

But I can't understand what the same hierarchy means.

We can't describe these path templates

  /pets/{petId}
  /pets/{name}

But we can describe these?

  /pets/{petId}
  /pets/{name}/hello

These depth of the hierarchy is different but these is different templated name in same depth of hierarchy.
When we get /pets/1/hello we can match bottom paths and name=1.
These is partially the same, but the whole is different.

So I want to add more example to this section.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Find the specification section containing the quoted “same hierarchy” rule and read the surrounding path-templating guidance. Add an example clarifying why /pets/{petId} and /pets/{name} conflict while the deeper /pets/{name}/hello path differs, then check that the wording matches the rule.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.