Does The developer portal support the swagger $ref reference as in the below.
investmentAllocations: type: array description: Investment Allocations items: $ref: "#/definitions/InvestmentAllocation" InvestmentAllocation: type: object properties: allocationType: type: string description: Allocation Type value: type: number description: The value of the allocation that the entity has made. currency: type: string description: The currency related to the value of the allocation that the entity has made. percent: type: number description: The entity's allocation as a percentage of their total. status: type: string description: The status of the allocation that the entity has made. source: type: string description: The source of the capital for the allocation that the entity has made. valueUSD: type: number description: The value of the allocation that the entity has made in U.S. Dollars. valueEUR: type: number description: The value of the allocation that the entity has made in Euros.
Yes, It does support. Developer portal shows samples request schema in smartdocs display even if they are referenced using $ref.
For example, See pet store OpenAPI spec here, which uses $ref to reference request schema.
If you take the example of Add Pet method, Sample request schema looks like below,
{ "in": "body", "name": "body", "description": "Pet object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Pet" } }
As you can see sample request body is constructed using $ref in OpenAPISpec. See it in action here. Hope it helps. Keep us posted if any.
We are using this method within our smartdocs with no issue in the DevPortal.
*HOWEVER* - Beware of using (what I think is a great way to define resource parameters) a $ref for discrete params within resources. Like:
...and then using the parameter references within a resource as in:
*THIS DOES NOT WORK*
Rendering within the DevPortal will properly show the schema in this case but does not show any discrete parameters that are defined as shown above. So a Swagger/OAS author cannot express their parameters within a root-level parameters: object and refer to the common definition within various resources. They MUST be articulated within every resource in which they are referenced.
So if a common parameter is utilized within multiple resources within the API, the author is exposed to misspelling or other errors of definition which may not be discovered immediately.
User | Count |
---|---|
1 | |
1 | |
1 | |
1 | |
1 |