Documenting an API with all operations under a single path

[willamowius]

I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:

/api?action=action1&some-param=1
/api?action=action2&other-aparam=2

If I would put all parameters under a single path, that would force all parameters under that path, too and would mix a lot of parameters that are only valid on certain actions.

The Swagger editor doesn't let me create multiple entries for the same path, even if the action parameter is required with a different value on each. and doesn't accept /api?action=action1 as a separate path either.

Is the unique path a requirement from Swagger or from the OpenAPI spec ?

Is there a good workaround how to handle this ?

Thanks!

[cobertvc]

/api?action=action1&some-param=1
/api?action=action2&other-aparam=2

[jeremyfiel]

Swagger is a tooling vendor for the OpenAPI specification. The OAS specification requires each path is unique up to the point of the ?, the query separator.

The way your api is designed makes it very difficult to construct a human readable OpenAPI description. OAS does not have any "scenario" type of description available. This means all possible query parameters of a single endpoint should be described. But there is no way to distinguish which sets of parameters will provide a different response payload. You can use examples to provide different representations of the payload and you can also provide multiple payloads using composition keywords such as oneOf or anyOf to describe the possible data instances.

openapi: 3.0.3
info:
  title: test
  version: 1.0.0
paths:
  /api:
    get:
      summary: summary of api
      parameters:
        - name: action
          in: query
          required: true
          schema:
            type: string
        - name: some-pararm
          in: query
          schema:
            type: string
        - name: other-pararm
          in: query
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema: 
                anyOf:
                  - $ref: "#/components/schemas/action_some-param"
                  - $ref: "#/components/schemas/action_other-param"
              examples:
                action_some-param:
                  value: {}
                action_other-param:
                  value: {}
components:
  schemas:
    action_some-param:
      type: object
      properties:
        some-param-payload:
          type: string
    action_other-param:
      type: object
      properties:
        other-param-payload:
          type: string

[handrews]

I've marked the correct answer and am closing this as resolved due to no further questions.

Note that OAS 4.0 "Moonwalk" is expected to support distinct operations using the same path under the "operation signatures" principle.