Implicit Path Parameters

[jewest27]

Breaking out this topic from issue #107.

In the absence of a supported truly hierarchical path approach it would be helpful to have implicit path parameters. Building on #/parameters in #107:

I propose the following, continue supporting the current parameter approach(es), including #107, unchanged. In the case of resolving the definition of path parameters:

1. Check for an explicit parameter definition on the path or operation
2. If an explicit definition for the {value} within the braces, use that definition
3. If not:
   1. Check for a parameter definition in #/parameters, by name
   2. If found, use that definition
   3. If not found, infer that it is a string parameter and is required (since it is in the path)

@earth2marsh @fehguy thoughts?

Example below

paths:
  /owner/{ownerId}/events/{eventNumber}:
    get:
      description: The events an Owner has participated in
      parameters:
# implicit ownerId path parameter
# explicit reference to defined parameter
        - $ref: "#/parameters/eventNumber"
          required: true
parameters:
  eventNumber:
    description: "The numerical path parameter, number of an event"
    name: eventNumber
    in: path
    type: number
    format: int32

[fehguy]

@jwest-apigee while convenient for human creation, that's going to create issues in tooling.

[jewest27]

FYI here is a sample we are working on: https://github.com/LXlagent3/Usergrid-API/blob/master/AdminUser.yaml where the verbosity (albeit better than 1.2) makes it quite long. In this case it is a hierarchical path pattern where orgId and appId are repeated on almost every path.

[earth2marsh]

Also, from #107, this would enable defining path parameters at the host or baseUrl level.

At some point we should revisit whether to diverge YAML and JSON to better support human authorship. It may be that the current approach is reasonably descriptive now, and it might remain compatible with that future, more convenient expression.

[fehguy]

guys, implicit params aren't going to happen in this release. But see here:

LXlagent3/Usergrid-API#1

[jewest27]

Awesome, you beat us to it :)

---

Jeff West | Products | apigee | m: +1.214.450.9378 | twitter @jeffreyawest @apigee | Skype jeffrey.a.west
I ♥ APIs 2014 | September 8-10 | Fort Mason Center | San Francisco | #iloveapis | iloveapis2014.com

On Aug 29, 2014, at 12:23 PM, Tony Tam [email protected] wrote:

guys, implicit params aren't going to happen in this release. But see here:

LXlagent3/Usergrid-API#1

—
Reply to this email directly or view it on GitHub.

[fehguy]

Honestly, I think having the UI create path params automatically would be a good way to go. It's not a spec issue per se but a "workflow automation"

[webron]

Closing this now. If this is something to take into account for a future version of the spec, please reopen at https://github.com/wordnik/swagger-spec.