Is there any possible way to define same path multiple times with change in parameters?

[narottam88]

I need to define a service that is used multiple times with change in parameters.I ran into a problem whenever I define it because when I define it second time, it automatically overwrites the previous one. Following is how I defined it.This is first definition:

  /sevice :
    post:
      summary: Service ABC
      description: |
        This service is used to get ABC.
      parameters:
        - name: XYZ
          in: query
          description: '8'
          required: true
          type: number
          format: integer
        - name: LMN
          in: query
          description: '2'
          required: true
          type: number
          format: integer
      tags:
        - ABC
      responses:
        '200':
          description: An array of products
          schema:
            type: array
            items:
              $ref: '#/definitions/ABC'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

This is the second definition:

 /sevice :
    post:
      summary: Service ABC
      description: |
        This service is used to remove ABC.
      parameters:
        - in: body
          name: jsonData
          description: Object that needs to be sended to the store.
          required: true
          schema:
            $ref: '#/definitions/PQR'
      tags:
        - ABC
      responses:
        '200':
          description: An array of products
          schema:
            type: array
            items:
              $ref: '#/definitions/LMN'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

Is it possible to have same path appear more than once in one API spec?

[webron]

The Swagger/OpenAPI spec currently doesn't allow specifying such operations. The combination of verb+path uniquely identify an operation, query parameters do not affect it.

[narottam88]

Thanks for the quick reply @webron .Hoping to see this feature soon in Swagger. Thanks again!!!

[C-h-e-r-r-y]

Ok, swagger 2.0 does not support this, but will it be supported in next version? (for my personal opinoin it is a big mistake to do not support such funcitonality)

[webron]

It's undecided yet.

[robreeves]

I also agree that this feature should be part of swagger. I assume that this constraint is the result of the view that RESTful APIs should strictly follow a RESTful architecture and each path should map to one resource. This isn't the case all of the time and sometimes an API can be represented in a more concise way by deviating from the REST architecture a little.

If this constraint is lifted and a single path can have multiple definitions with different parameters then all current cases can still be supported and it will enable more APIs to use swagger. I'd be interested to hear the counter argument. The only thing I can think is that a stricter specification keeps people from writing sloppy, nonuniform APIs, but I'm not sure if that is the role swagger should play.

For completeness, my specific use case is a single path that takes different body parameter types based on a header value. My plan was to define multiple path definitions for each header value and body parameter type pair. I could move the header value that results in a different body type to the path, but I am implementing a spec that generically defines header values independent of the transport protocol chosen. Conceptually, it matches the spec by keeping these as headers instead of putting them in the path.

Even with this constraint, swagger is awesome. Thanks for the great work.

[cskru]

Is there a solution for this issue now? I'd like to be able to distinguish 2 apis with same base path but,

1. Plane path without and path params
2. Pass query params.

A solution to this issue would be helpful to accomplish the same.

[kaushalsmile08]

Is swagger cached docs. As i removed some class from openApi.configuration.resourceClasses init params of web.xml but still swagger reading it and din't used new class path value which is passed in param-value

[san02]

I have a similar issue. I have two routes in which one's path is part of the second one. Eg. 1. GET /static/path/{id}

2. GET /path/{id} when i try to document it with swagger, i could not find the /static/path/{id} in the swagger UI after building. though, no error is thrown. Any idea how to resolve this.?

[Hantick]

Is it possible to have multiple HttpDelete methods in Swagger controller? I mean I would like to have other routes in methods ConfirmReservation and CancelReservation, which both of them requires reservation id. Different route, same paramteres, different action.

[ben1226q]

The Swagger/OpenAPI spec currently doesn't allow specifying such operations. The combination of verb+path uniquely identify an operation, query parameters do not affect it.

if there are any solution now??

[webron]

@ben1226q nope. This has nothing to do with the editor, but with the spec. If you'd like to see a change, voice your opinion at https://github.com/OAI/OpenAPI-Specification/.

[link89]

@ben1226q FYI: https://github.com/OAI/OpenAPI-Specification/issues/1635

[cheslijones]

An example of where something like this would be useful... the QuickBooks Online API I'm working with and trying to automate with Microsoft Power Automate. Create a customer

POST /v3/company/<realmID>/customer

Content type:application/json
Production Base URL:https://quickbooks.api.intuit.com
Sandbox Base URL:https://sandbox-quickbooks.api.intuit.com

{
  "FullyQualifiedName": "King Groceries", 
  "PrimaryEmailAddr": {
    "Address": "jdrew@myemail.com"
  }, 
  "DisplayName": "King's Groceries", 
  "Suffix": "Jr", 
  "Title": "Mr", 
  "MiddleName": "B", 
  "Notes": "Here are other details.", 
  "FamilyName": "King", 
  "PrimaryPhone": {
    "FreeFormNumber": "(555) 555-5555"
  }, 
  "CompanyName": "King Groceries", 
  "BillAddr": {
    "CountrySubDivisionCode": "CA", 
    "City": "Mountain View", 
    "PostalCode": "94042", 
    "Line1": "123 Main Street", 
    "Country": "USA"
  }, 
  "GivenName": "James"
}

Full update a customer

POST /v3/company/<realmID>/customer

Content type:application/json
Production Base URL:https://quickbooks.api.intuit.com
Sandbox Base URL:https://sandbox-quickbooks.api.intuit.com

{
  "domain": "QBO", 
  "PrimaryEmailAddr": {
    "Address": "Surf@Intuit.com"
  }, 
  "DisplayName": "Bill's Windsurf Shop", 
  "PreferredDeliveryMethod": "Print", 
  "GivenName": "Bill", 
  "FullyQualifiedName": "Bill's Windsurf Shop", 
  "BillWithParent": false, 
  "Job": false, 
  "BalanceWithJobs": 85.0, 
  "PrimaryPhone": {
    "FreeFormNumber": "(415) 444-6538"
  }, 
  "Active": true, 
  "MetaData": {
    "CreateTime": "2014-09-11T16:49:28-07:00", 
    "LastUpdatedTime": "2015-07-23T11:07:55-07:00"
  }, 
  "BillAddr": {
    "City": "Half Moon Bay", 
    "Line1": "12 Ocean Dr.", 
    "PostalCode": "94213", 
    "Lat": "37.4307072", 
    "Long": "-122.4295234", 
    "CountrySubDivisionCode": "CA", 
    "Id": "3"
  }, 
  "MiddleName": "Mac", 
  "Taxable": false, 
  "Balance": 85.0, 
  "SyncToken": "3", 
  "CompanyName": "Bill's Windsurf Shop", 
  "FamilyName": "Lucchini", 
  "PrintOnCheckName": "Bill's Wind Surf Shop", 
  "sparse": false, 
  "Id": "2"
}

Definitely makes it a real pain because these are two distinct actions, but use the same path and verb. Really, the only difference is the request body.

[akrestan]

Hello,

Has there been any shift in opinions on this subject recently? I too could take advantage of being able to distinguish Swagger documented methods by a different set of query parameters. Thanks in advance for responses.

[amouratoglou]

Hi guys, I'm having a similar issue, is there a way to document the different request bodies for the same endpoint ? can't seem to find how.

[levkany]

hi guys! if it helps someone, one can do the following:

GET /cases/{caseId}/exam-document/comments POST /cases/{caseId}/exam-document/comments/

by adding the last "/" the endpoints are considered unique in case you need all 4 types you can span the "/" but it is not recommended ;)

[kairos0ne]

I honestly wouldn't know why this wouldn't be supported there are multiple cases where documentation variations are required given a single path.

Personally I'm building an API with Plug Elixir that is an abstraction given a valid schema a single endpoint takes crud actions as JSON.

A request looks like this:

{
    "action": "create",
    "type": "data",
    "body": {
        "id": "d375d04d-5e7c-41a6-abd6-36d4fb5a4a07",
        "schema": [
            {
                "key": "name",
                "value": "kairos0ne"
            },
            {
                "key": "email",
                "value": "kairos0ne@example.com"
            },
            {
                "key": "password",
                "value": "123456"
            }
        ]
    }
}

The whole app uses a single endpoint /api/v1/ and only takes post requests.

Depending on the schema it routes appropriately.

Using path as the unique ID therefore flat out means this library is not fit for purpose for any app that isn't restful.

[elanh]

Also looking for a solution here - need support for multiple endpoints in order to do JSON-RPC post requests that all use the apiKey as the endpoint but specify the method name in the body.

[MathScheffer]

hi guys! if it helps someone, one can do the following:

GET /cases/{caseId}/exam-document/comments POST /cases/{caseId}/exam-document/comments/

by adding the last "/" the endpoints are considered unique in case you need all 4 types you can span the "/" but it is not recommended ;)

BLESSED!

[tisonkun]

Here is a case in https://github.com/apache/pulsar/issues/18947 that of same path + verb but different consumes.