1

Example:

This is the first definition:

/**
 * @swagger
 * /a/b/items:
 *   get:
 *     description: Get all the items
 *     responses:
 *      200:
 *          Returns an array of items
 */

This is the 2nd definition:

/**
 * @swagger
 * /a/b/items:
 *   get:
 *     description: Get items by ids
 *     parameters:
 *      - name: ids
 *        in: query
 *        required: true
 *        schema:
 *          $ref: '#/definitions/itemIds'
 *
 *     responses:
 *      200:
 *          description: Returns an array of items, given the itemIds
 */

It is clear that, the difference here lies in the request structure. Note that, for the second definition, I wanna pass the parameter ids in query.

The first definition is a simple get request without any path parameters or query parameters.

The second definition is a get request with same base path but with query params.

When I define these two in succession, the second definition over writes the first one and the Swagger UI shows the second one only.

It's highly desirable to have these two definitions as unique ones.

Any solutions/thoughts/ways to accomplish the uniqueness?

Changing the apis to support documentation is simply a "No go"!

Any help will be much appreciated. Thanks in advance!

Kruthika C S
  • 729
  • 1
  • 7
  • 18
  • Removing the first definition and having 2nd definition with required: false for the query param and suitable description will provide a temporary solution. But since these 2 definitions are wrt 2 unique endpoints, it is highly desirable to have 2 unique definitions. – Kruthika C S Dec 05 '17 at 05:29
  • OpenAPI/Swagger [does not support](https://stackoverflow.com/q/40495880/113116) paths that only differ in query parameters. You can either have a single path with an optional query parameter, or change the 2nd path to use a path parameter instead of query parameter. There are no other ways. – Helen Dec 05 '17 at 10:31
  • 1
    Related proposals in the OpenAPI specification repository: [Accommodate legacy APIs by allowing query parameters in the path](https://github.com/OAI/OpenAPI-Specification/issues/123), [Querystring in Path Specification](https://github.com/OAI/OpenAPI-Specification/issues/164) – Helen Dec 05 '17 at 10:38

1 Answers1

0

I believe the endpoint in the 2nd definition needs to be changed to:

/a/b/items/{ids}:
Mike
  • 676
  • 1
  • 8
  • 17
  • As I have clearly mentioned, the parameters are in query. Not path params. Thanks for considering to answer though. – Kruthika C S Dec 05 '17 at 04:05
  • 2
    OK, query params, not path ... got it! Because you can't have duplicate endpoints, how about removing the first definition, and in the 2nd definition change required: to false. I know that you'll have to change the descriptions, but that will be unavoidable. – Mike Dec 05 '17 at 04:39
  • 1
    I can see what you are saying.. It kind of gives a temporary solution. But, these two are 2 separate apis and it is desirable that each of them have unique definitions. Your suggestion provides a temporary solution though. – Kruthika C S Dec 05 '17 at 05:08