Allow the definition of an API path with template (like RFC6570)

[nelsg]

In RFC6570, it is possible to define an URI Template like that : http://www.example.com/foo{?query,number}

The expansion process for expressions beginning with the question-mark ("?") operator follows the same pattern as form-style interfaces on the World Wide Web.

[webron]

Are you referring specifically to https://tools.ietf.org/html/rfc6570#section-3.2.8?

[nelsg]

Yes,

If I use an API path like "/pet{?x,y}", swagger-editor raise an error because it expects a parameter called "{?x,y}". I think this is an issue but I found nothing about this case in swagger 2.0 specification.
It would be better to amend swagger-spec before to open an issue for swagger-editor, provided this is approved, of course.

[webron]

How is that different than specifying two query parameters called x and y?

[nelsg]

As for path parameters, it's a complement to specifying two query parameters called x and y.

In swagger-editor, if I define a path like "/pet/{x}/{y}, it expects two path parameters called "x" and "y". Otherwise, if I define a path like "/pet{?x,y}", it expects one path parameter called "?x,y" instead of expecting two query parameters called "x" and "y".

[webron]

These are not path parameters, these are query parameters (the RFC refers to them as query as well). and I fail to see the difference between that and declaring two query parameters. Can you clarify the difference?

[nelsg]

There are no differences, it's just a clarification for the path.

I'm using this notation, maybe I'm wrong and swagger-editor returns 2 errors :

{
  "swagger" : "2.0",
  "info" : {
    "title" : "usr",
    "version" : "0"
  },
  "host" : "127.0.0.1",
  "basePath" : "/",
  "paths": {
    "/user/{id}": {
      "get": {
        "summary" : "Get user",
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "description" : "User id to fetch",
          "required" : true,
          "type" : "string"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"
            }
          }
        }
      }
    },
    "/user/{?firstName,lastName,birthDate}": {
      "get": {
        "summary" : "Get users",
        "parameters" : [ {
          "name" : "firstName",
          "in" : "query",
          "description" : "User first name criteria",
          "required" : false,
          "type" : "string"
        }, {
          "name" : "lastName",
          "in" : "query",
          "description" : "User last name criteria",
          "required" : false,
          "type" : "string"
        }, {
          "name" : "birthDate",
          "in" : "query",
          "description" : "User birth date criteria",
          "required" : false,
          "type" : "string",
          "format" : "date-time"
        }],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "items": {
                "$ref": "#/definitions/User"
              },
              "type": "array"
            }
          }
        }
      }
    }
  },
  "definitions": {
   "User" : {
      "description" : "Step of the delivery workflow",
      "properties" : {
        "firstName" : {
          "description" : "User first name",
          "type" : "string"
        },
        "lastName" : {
          "description" : "User last name",
          "type" : "string"
        },
        "birthDate" : {
          "description" : "User birth date",
          "type" : "string",
          "format" : "date-time"
        }
      },
      "type" : "object"
    }
  }
}

[webron]

We don't support that notation and it's not really required. Just use the path /user/, keep the query parameters as you've described them and you're done.

[nelsg]

ok

[dilipkrish]

I think this needs to be supported and in a way related to this swagger spec issue. In spring we are able to have different controller methods based on query parameters specified. One could argue that it can be implemented as one path with a union of all the query parameters, but for a richer experience (I'm thinking hypermedia), the path needs to support link templates.

[webron]

Are you sure you linked to the right place, @dilipkrish?

[webron]

I can see it being related to #164, but then that's what we have #164 for. For the requirements @antyriad raised, there's already a solution.

[dilipkrish]

Yeah its vaguely related :) and I'll tell u why; its the corollary to the problem of one path multiple response/representations. Going by the example in that issue, instead of headers what if I decided to do that as part of the url

http://host/api/service/test?v=1 vs. http://host/api/service/test?v=2

Another more pertinent example to this issue is the use case is where

http://host/api/service/find{?name,email} - maps to a controller method findByNameAndEmail

http://host/api/service/find{?state} - maps to a controller method findByState

In both cases the path is the same, but the required parameters are a distinct set of required fields. So I'd like to represent them as unique paths.

[webron]

That's pretty much #164.

[dilipkrish]

Yes absolutely, but this is a more specific on how it should be implemented in a standards compatible fashion.

[webron]

I agree, but let's add that information there instead of diverting it to a separate issue.

[vaishalitekale]

you can check you swagger code with the online editor. please follow below link

http://editor.swagger.io/#/

[dilipkrish]

@webron @fehguy Shouldn't this issue be linked to a meta issue regarding url path templates. Or may be close asa a duplicate of #291

[fehguy]

What we've added is here:

#804