When referencing a domain, you would use the following to get the CommonSchema model from the CommonDomain domain
$ref: 'https://api.swaggerhub.com/domains/CompanyName/CommonDomain/1.0.0#/components/schemas/CommonSchema'
How can you make a reference to another existing api? This is being done from another API within Swaggerhub. When I attempt to do something like this to get the SomeSchema model
$ref: 'https://api.swaggerhub.com/apis/CompanyName/SomeApi/1.0.0#/components/schemas/SomeSchema'
I get an error saying that it Could not resolve reference: 404 Unknown Domain CompanyName/SomeApi:1.0.0
This would be legal for swagger codegen to generate from. Is this just a limitation of swaggerhub? If not, how does one go about doing this properly?
This functionality does not exist in SwaggerHub. You can only reference an object from a domain file in SwaggerHub, not an API file.
This is how I think about it:
Any object in a domain file can be referenced by any other file (within the same org).
Objects with an API file can only be referenced within the same file.
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.
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.
I'm writing a restful XML API for a university assignment, the spec requires no HTML frontend.
There doesn't seem to be any documentation (or guessable functionality) regarding how to change the default format? Whilst thus far I have created all templates as ...Success.xml.php it would be easier to just use the regular ones and set this globally; I really expected this functionality to be configurable from YAML.. yet I have found some hard coded references to the HTML format.
The main issue I'm encountering is that part of the assessment is returning a 404 in a certain way (not as a 404 :/), but importantly it must always return XML, and the default setup of a missing route is a HTML 404 not XML (so it only works when I use forward404 from an action running via a XML route.
So in summary, is there a way to do this / what class(es) do I have to override?
Try putting this in factories.yml
all:
request:
class: sfWebRequest
param:
default_format: xml
That will still need the template names changing though. It will just mean that urls that don't specify a format will revert to xml instead of html.
You can subclass sfPHPView and override the initialise method to affect this (copy paste the initialise method from sfView) - the lines like this need changing:
if ('html' != $format)
You then need to change the view class used ... try this:
http://mirmodynamics.com/post/2009/02/23/symfony%3A-use-your-own-View-class