Documenting an API with all operations under a single path #3344
-
I'm trying to document an existing API that uses a single path with query parameters to specify the different actions:
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 Is the unique path a requirement from Swagger or from the OpenAPI spec ? Is there a good workaround how to handle this ? Thanks! |
Beta Was this translation helpful? Give feedback.
Replies: 3 comments
-
/api?action=action1&some-param=1 |
Beta Was this translation helpful? Give feedback.
-
Swagger is a tooling vendor for the OpenAPI specification. The OAS specification requires each path is unique up to the point of the 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 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
|
Beta Was this translation helpful? Give feedback.
-
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. |
Beta Was this translation helpful? Give feedback.
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 asoneOf
oranyOf
to describe the poss…