I'm trying to turn the Atom Publishing Protocol (RFC5023) in to a Swagger / OpenAPI spec to exercise writing those specs.
I ran into the following problem: in Atom there are different types of URIs, e.g. Collection and Member URIs.
My idea was to document it like this:
paths:
/{CollectionURI}:
get:
summary: List Collection Members
...
post:
summary: Create a Resource
...
parameters:
- $ref: "#/parameters/CollectionURI"
/{MemberURI}:
get:
summary: Retrieve a Resource
...
parameters:
- $ref: "#/parameters/MemberURI"
When I do that, swagger-editor claims that
Equivalent path already exists: /{MemberURI}
Those are different types of URIs that return different things when queried. I want to call them differently to document them individually.
Is there any way to do this?
Thanks!
EDIT:
The spec shows up just fine in Swagger-UI -- is this a bug in the editor or does the UI just ignore my error?
That's because the two paths can be identical. I understand that the parameters may uniquely identify them, but OpenAPI 2.0 (Swagger 2.0), 3.0 and 3.1 do not support full URI templates, and the path portion alone is inspected for uniqueness. So these:
/{foo}
/{bar}
are identical, even if foo must be a string, and bar must be a number. Please add your $0.02 on the OpenAPI Specification Repo as we're working on better path support right now.
Related
I have spent a lot of time trying to figure out what OpenAPI Links can be used for and how they relate to hypermedia links in the body of a response & it's doing my head in!
Lets say the simple class model below represents the business domain for which we have defined an OpenAPI spec that provides paths to navigate the instances of the various classes.
For example, if I perform a get of /borrowers/{id}, I would expect the response to contain both the properties of Borrower and a means to follow R1 or R2 to get the relevant set of Book instances.
Before OpenAPI 3 I would have constructed links to the relevant paths e.g.
/borrowers/{id}/loaned-books or /borrowers/{id}/reserved-books and included those as properties (hyperlinks) in the definition of the response body.
At runtime, if I followed those hyperlinks I would get an array of the relevant Books each of which had other hyperlinks.
So the OpenAPI Link questions are:
Are they a replacement for the need to generate hyperlinks in the response? I don't think so but in which case
What is the Runtime Expression Language (REL) for?
Are they just a means of defining hyperlinks in the API spec? Possibly but in which case does the response body definition still need to include properties for those links? Presumably their values still need to have the actual hyperlinks created on the server?
Given that the REL doesn't allow wildcards how do you define links when the response is an array of resources, each of which has an id to be used by the next operation?
Any help explaining links would be gratefully received.
I know this may be a silly question but i cannot find out how to change (get rid of) the code after my resource name in schemas section generated with OpenApi (Swagger) of the ApiPlatform.
Definitoins are loaded by the phpdoc of my DTO ClienteDtoOutput, but where/how can i change the Clienti:58c4a823efd9bfeab158f60692e79e88 name?
I'm trying to turn the Atom Publishing Protocol (RFC5023) in to a Swagger / OpenAPI spec to exercise writing those specs.
I ran into the following problem: in Atom there are different types of URIs, e.g. Collection and Member URIs.
My idea was to document it like this:
paths:
/{CollectionURI}:
get:
summary: List Collection Members
...
post:
summary: Create a Resource
...
parameters:
- $ref: "#/parameters/CollectionURI"
/{MemberURI}:
get:
summary: Retrieve a Resource
...
parameters:
- $ref: "#/parameters/MemberURI"
When I do that, swagger-editor claims that
Equivalent path already exists: /{MemberURI}
Those are different types of URIs that return different things when queried. I want to call them differently to document them individually.
Is there any way to do this?
Thanks!
EDIT:
The spec shows up just fine in Swagger-UI -- is this a bug in the editor or does the UI just ignore my error?
That's because the two paths can be identical. I understand that the parameters may uniquely identify them, but OpenAPI 2.0 (Swagger 2.0), 3.0 and 3.1 do not support full URI templates, and the path portion alone is inspected for uniqueness. So these:
/{foo}
/{bar}
are identical, even if foo must be a string, and bar must be a number. Please add your $0.02 on the OpenAPI Specification Repo as we're working on better path support right now.
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.
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.)