So I have a path that is using a referenced param, but the referenced param isn't required: true, which I would like to add on. I thought I could use the following syntax for that:
operationId: getReports
summary: Get the reports
parameters:
- $ref: '#/parameters/reportStartDate'
required:true
- $ref: '#/parameters/reportEndDate'
required:true
However, this doesn't seem to work the way I would expect. It also seems that I can't use allOf, since that only works for combining too objects.
Does anyone have a way of doing this?
Properties of $ref'd parameters cannot be overridden. You'll need to redefine the parameter entirely.
Related
I have multiple paths that require an id number. There are some paths where multiple ids are required.
I know that I can reference a parameter when building a path.
paths:
/path1/{path1ID}
parameters:
- $ref: '#/components/parameters/path1ID_param'
components:
parameters:
path1ID_param:
name: path1ID
in: path
schema:
type: integer
If I do it this way, I'm going to have a lot of repeated definitions where the only change is the name. This grates.
Is there a way I can override the name in the path definition? I have tried variations of allOf but haven't hit on anything yet. I've searched the swagger documentation without much luck. I've searched here and found a lot of interesting pointers that helped me refine my API ... but I found nothing related to what I'm trying to do.
Is it possible to do something like this?
paths:
/path1/{path1ID}
parameters:
- $ref: '#/components/parameters/parmID_param/'
- name: path1ID
/path1/{path1ID}/subpath2/{subpath2ID}
- $ref: '#/components/parameters/parmID_param/'
- name: path1ID
- $ref: '#/components/parameters/parmID_param/'
- name: subpath2ID
components:
parameters:
path1ID_param:
name: path1ID
in: path
schema:
type: integer
This is not supported.
As of OpenAPI 3.1, you can only override the description of a referenced parameter, but not its name or other attributes (required, style, etc.).
Here are existing feature requests in the OpenAPI Specification repository:
Extend/override properties of a parameter
Allow required as sibling of $ref (like summary/description)
I'm trying to build a simple Swagger model:
PlayerConfig:
type: object
required:
- kind
- player_id
properties:
kind:
type: string
example: PlayerConfig
player_id:
type: string
example: "foo"
description: "bar"
sports_config:
oneOf:
- $ref: '#/components/schemas/PlayerConfig'
discriminator:
propertyName: kind
For some reason the generated HTML does not show the player_id's example field. This makes me think I'm not doing this correctly.s
So the question is if using a model as a type can in fact be done as I'm trying to do. example field does get rendered if its parent is parameters: instead of properties:.
Update: I read Object and Property Examples section on https://swagger.io/docs/specification/adding-examples/ and it seems like my code snippet should have worked.
Update #2: I actually downloaded redoc-cli (which is a CLI tool for OpenAPI -> html bundle) and took a sample spec from Swagger Editor that has example field under properties that mimics my problem and it looks like it's expected (see the screenshot I attached):
If the string value contains spaces (or some other special characters), you should enclose it in quotes. So the line should read
example: "LeBron James"
This question is not a duplicate of (Swagger - Specify Optional Object Property or Multiple Responses) because that OP was trying to return a 200 or a 400.
I have a GET with an optional parameter; e.g., GET /endpoint?selector=foo.
I want to return a 200 whose schema is different based on whether the parameter was passed, e.g.,:
GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah -> {200, schema_2}
In the yaml, I tried having two 200 codes, but the viewer squashes them down as if I only specified one.
Is there a way to do this?
Edit: the following seems related: https://github.com/OAI/OpenAPI-Specification/issues/270
OpenAPI 2.0
OAS2 does not support multiple response schemas per status code. You can only have a single schema, for example, a free-form object (type: object without properties).
OpenAPI 3.x
In OAS3 you can use oneOf to define multiple possible request bodies or response bodies for the same operation:
openapi: 3.0.0
...
paths:
/path:
get:
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseOne'
- $ref: '#/components/schemas/ResponseTwo'
However, it's not possible to map specific response schemas to specific parameter values. You'll need to document these specifics verbally in the description of the response, operation and/or parameter.
Here's a possibly related enhancement request:
Allow operationObject overloading with get-^ post-^ etc
Note for Swagger UI users: Older versions of Swagger UI (before v. 3.39.0) do not automatically generate examples for oneOf and anyOf schemas. As a workaround, you can specify a response example or examples manually. Note that using multiple examples require Swagger UI 3.23.0+ or Swagger Editor 3.6.31+.
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseOne'
- $ref: '#/components/schemas/ResponseTwo'
example: # <--- Workaround for Swagger UI < 3.39.0
foo: bar
I wanted the same thing, and I came up with a workaround that seems to work:
I´ve just defined two different paths:
/path:
(...)
responses:
200:
description: Sucesso
schema:
$ref: '#/definitions/ResponseOne'
(...)
/path?parameter=value:
(...)
responses:
200:
description: Sucesso
schema:
$ref: '#/definitions/ResponseTwo'
(...)
Paths do work on swagger editor. I can even document each option differently and put optional parameters that only may be on the second case toguether, making the API doc much cleaner. Using operationId you may generate cleaner names for the generated API methods.
I´ve posted the same solution here (https://github.com/OAI/OpenAPI-Specification/issues/270) to verify if I am missing something more.
I do understand it is not explicitly allowed/encouraged to do it (neither I found some place explicitly disallowing it). But as a workaround, and being the only way to document an API with this behaviour in the current specification,, looks like an option.
Two problems I´ve found out with it:
Java code gen URL escapes the "=" sign, therefore it wont work unless
you fix this in the generated code. Probably it happens in other code
generators.
If you have more query params it will add an extra "?" and fail;
If those are not blockers, it at least will allow you to document properly such cases and allow testing with swagger editor.
There is a function in my REST web service working with GET method and it has two optional parameters.
I tried to define it in Swagger but I encountered an error, Not a valid parameter definition, after I set the required as false.
I found out that if I set the required value as true the error will be gone. Here is a sample of my Swagger code.
...
paths:
'/get/{param1}/{param2}':
get:
...
parameters:
- name: param1
in: path
description: 'description regarding param1'
required: false
type: string
- name: param2
in: path
description: 'description regarding param2'
required: false
type: string
I didn't experience this with parameters in body or the the ones in query. I think this problem is only related to parameters in path. I could not find any solution in swagger specification files either.
Is there any other way to define optional parameters in Swagger or do I have any mistake in my code?
Any help would be appreciated.
Given that path parameter must be required according to the OpenAPI/Swagger spec, you can consider adding 2 separate endpoints with the following paths:
/get/{param1}/{param2} when param2 is provided
/get/{param1}/ when param2 is not provided
It it likely blowing up because you cannot have a base uri parameter optional, only query string values (in the case of a url).
For example:
GET /products/{id}/pricing?foo=bar
** If foo is optional then your IN parameter needs to be "query" not "path"
** If {id} is optional then something is wrong. {id} can't be optional because it is contained within the base uri.
This should work:
{
"in":"query",
"required":false
}
This should not work
{
"in":"path",
"required":false
}
change your "in" property to be "query" instead of "path" and it should work.
Your YAML fails because as it stated on the specification:
Determines whether this parameter is mandatory. If the parameter is in "path", this property is required and its value MUST be true.
Source: http://swagger.io/specification/#parameterObject (Look in fixed fields table)
Sad but fact there is no official support for optional parameters still in 2020 and in 3.* specification:
https://github.com/OAI/OpenAPI-Specification/issues/93
You can only apply some workaround mentioned in other answers (describe several endpoints for every set of parameters; convert your API to work with query-parameters instead of path-parameters).
Personally I decided to just leave everything as is, just add a parameter description which clearly says "This parameter is OPTIONAL!". Should be clear enough for everyone who reads the API.
Try adding 2 endpoints for the same API. like
/get/{param1}/{param2} and /get/{param1}/{param2}/{param3}
I'm working on an API spec in swagger that has an endpoint:
/authorizations
I would like to define an alternative spelling (authorisations) for this endpoint as well. Is this possible? Or do I need to define a separate route for each spelling?
/authorizations:
get:
description: Returns a list of authorizations
A possible workaround is to define another path that $refs the original path, this way you end up with two copies of the same path.
paths:
/authorizations:
get:
description: Returns a list of authorizations
responses:
200:
description: OK
/authorisations:
$ref: '#/paths/~1authorizations'
One limitation of this technique is that you cannot have operationId for these paths, because both paths will end up with the same ID, which is not allowed.
If you need to have different operationId in paths, you'll need to define the 2nd path in the usual way (i.e. copy-paste the definition from the 1st path).
Swagger currently does not support overloading/aliasing path definitions. I don't recall ever seeing such a request, but you're more than welcome on open an issue on https://github.com/wordnik/swagger-spec asking to add support for it in future versions.
See https://github.com/OAI/OpenAPI-Specification/issues/213 where one suggestion is to define a "renamed" path by using a 308 redirect:
/original-x:
description: Redirects to the new X
get:
responses:
'308':
description: This resource has been moved
headers:
Location:
schema:
type: string
default: /new-x
(I've not seen another means to implement this cleanly.)