Polymorphic Type Response

[terrancesnyder]

Hello, I seem to have an issue getting documentation given a response object.

Assume the following basic example, classic pet shop inheritance..

AnimalTargeting

• array[AnimalTarget] include
• array[AnimalTarget] exclude

AnimalTarget (object)
.. definition here...

AnimalCatTarget (AnimalTarget)
.. definition here...

AnimalDogTarget (AnimalTarget)
.. definition here...

AnimalBirdTarget (AnimalTarget)
.. definition here...

Assume I expose a object with:

PetShopCoupon (object)

• targeting (AnimalTargeting) - The animal targeting you want to use.

Because I have polymorphic types, the generated documentation doesn't really give a detailed list of all available options, so it's becomes close to impossible to not provide alternative documentation for the other polymorphic types.

I was hoping the API generated/documentation would provide "Possible Types to Use..." or a "more types available..." so that a user could explore the options.

Am I missing this feature someplace?

[kylef]

MSON allows you to declare "sample" values, these are values that can be used as samples but they do not restrict what may be a permitted value. Sounds like this may be what you are looking for, for example:

# My API

## GET /

+ Response 200 (application/json)
    + Attributes (array[AnimalTarget], fixed-type)
        + Sample
            + (AnimalCatTarget)
            + (AnimalDogTarget)

## Data Structures

### AnimalTarget

+ type (required)

### AnimalCatTarget (AnimalTarget)

+ type: cat (fixed)

### AnimalDogTarget (AnimalTarget)

+ type: dog (fixed)

We've delcared that our response is an array of AnimalTarget, and we've provided two example values.

Unfortunately, there are two bugs which makes this not work as expected, one in the parser (apiaryio/drafter#519) where the generated JSON bodies are not using the samples. We've attempted to fix this in apiaryio/drafter#587 but it's become complex to solve and we're unsure if we'll be able to solve this with a significant breaking change to the compiled form of API Blueprints (API Elements). You could perhaps work around this by providing your own JSON body which is the sample value to be used, for example:

# My API

## GET /

+ Response 200 (application/json)
    + Attributes (array[AnimalTarget], fixed-type)

    + Body
    
            [
                { "type": "cat" },
                { "type": "dog" }
            ]

## Data Structures

### AnimalTarget

+ type (required)

Which will show the following JSON example in mock servers and documentation:

Secondly, the other bug I referred to is apiaryio/attributes-kit#489 which affects Apiary's documentation rendering of the attributes.

[kylef]

Perhaps you could achieve what you are looking for by declaring the potential values inside the array, for example:

FORMAT: 1A

# My API

## GET /

+ Response 200 (application/json)
    + Attributes (array)
        + (AnimalCatTarget)
        + (AnimalDogTarget)

## Data Structures

### AnimalCatTarget (AnimalTarget)

+ type: cat (fixed)

### AnimalDogTarget (AnimalTarget)

+ type: dog (fixed)

This can be rendered as: