Is $ref supported in SmartDocs

[#1]

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.

[anilsr]

@Daniel Barnes ,

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.

[prokor1]

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.