Array description guideline

[PedroDiez]

What type of PR is this?

• documentation

What this PR does / why we need it:

This PR manages the cases when a response or specific field is an array so as their description is well renderized.

It applies for #547:

• For request scenarios guideline already exists 5.7.5. Request Bodies

• For response scenarios this PR adds a guideline in section 5.8.2. Responses

Which issue(s) this PR fixes:

Fixes #547

Does this PR introduce a breaking change?

• Yes
• No

Special notes for reviewers:

Changelog input

 guideline for array descriptions

Additional documentation

This section can be blank.

docs

[rartych]

Case B shows the property items referencing a schema that itself is an array. That results in an array-of-arrays, maybe this would be sufficient:

```yaml
components:
  schemas:
    <schema-name>:
      type: object
      properties:
        <property-name>:
            $ref: "#/components/schemas/<schema-item-name>"
...
    <schema-item-name>:
      type: array
      items:
        type: string
        description: <description>

[PedroDiez]

Case B shows the property items referencing a schema that itself is an array. That results in an array-of-arrays, maybe this would be sufficient:

```yaml
components:
  schemas:
    <schema-name>:
      type: object
      properties:
        <property-name>:
            $ref: "#/components/schemas/<schema-item-name>"
...
    <schema-item-name>:
      type: array
      items:
        type: string
        description: <description>

Yes, i agree. Thanks for the catch-up. Will also name to <schema-array-name>

[rartych]

LGTM

[Kevsy]

LGTM

[patrice-conil]

LGTM

[tlohmar]

Can you add another example, when a $ref keyword is used for the item data type?

[PedroDiez]

Can you add another example, when a $ref keyword is used for the item data type?

Thinking about the comment, guess we can add other scenario covering that:

Case C: Specific field is an array and their items are reference by $ref keyword

components:
  schemas:
    <schema-name>:
      type: object
      properties:
        <property-name>:
          $ref: "#/components/schemas/<schema-array-name>"
...
    <schema-array-name>:
      type: array
      items:
        $ref: "#/components/schemas/<schema-item-name>"
...      
    <schema-item-name>:
      type: object
      properties:
        <item-object-property1-name>:
          type: string
          description: <description>
        <item-object-property2-name>:
          type: boolean
          description: <description> 

@tlohmar, @rartych wydt?

[tlohmar]

Thx

[rartych]

I have returned to that proposal and I see some changes are needed:

• as it is releted to Responses section it should be placed in 5.7.6. Responses
• since we have in 5.7.6 general responses template:

responses:
  "2xx":
    description: <description>
    headers:
      x-correlator:
        $ref: "#/components/headers/x-correlator"
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/<schema-name>"
  "4xx":
    $ref: "#/components/responses/<schema-name>"
  "5xx":
    $ref: "#/components/responses/<schema-name>"

We can clarify it with changing <schema-name> to dedicated schema-name templates: <success-reponse-schema-name>, <4xx-schema-name>...

• Then for Case A (although it is about schemas in components, but is realated to response) the template can be simple:

components:
  schemas:
    <success-reponse-schema-name>:
      type: array
      items:
        type: string
        description: <description>

• Case B is more complicated because the simplest way is using array inline and for that the description under <property-name> should work:

components:
  schemas:
    <success-reponse-schema-name>:
      type: object
      properties:
        <property-name>:
          description: <description>
          type: array
          $ref: "#/components/schemas/<schema-array-item>"
...
    <schema-array-item>:
        description: <description>
        type: string

The example is in - Device reachability status API Redoc - I modified it to follow this template

• Case B2 when array is reusable - here the description at array level seems to work in Redoc, the description on items level is not visible in Redoc

components:
  schemas:
    <success-reponse-schema-name>:
      type: object
      properties:
        <property-name>:
          $ref: "#/components/schemas/<schema-array-name>"
...
    <schema-array-name>:
      type: array
      description: <description>
      items:
        type: string
        description: <description>

The example with the same Device reachability status API Redoc - different branch

In summary:

• we need to document Case A,
• case B/B1 is strightforward (we already have requirement to add description to each schema, it should work)
• case C can be seen as over-engineered introducing intermediate array schema

If needed we can think of guidelines for array schema definitions in 5.8.1.
WDYT?
I am sorry for so late remarks.

[PedroDiez]

I have returned to that proposal and I see some changes are needed:

• as it is releted to Responses section it should be placed in 5.7.6. Responses
• since we have in 5.7.6 general responses template:

responses:
  "2xx":
    description: <description>
    headers:
      x-correlator:
        $ref: "#/components/headers/x-correlator"
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/<schema-name>"
  "4xx":
    $ref: "#/components/responses/<schema-name>"
  "5xx":
    $ref: "#/components/responses/<schema-name>"

We can clarify it with changing <schema-name> to dedicated schema-name templates: <success-reponse-schema-name>, <4xx-schema-name>...

• Then for Case A (although it is about schemas in components, but is realated to response) the template can be simple:

components:
  schemas:
    <success-reponse-schema-name>:
      type: array
      items:
        type: string
        description: <description>

• Case B is more complicated because the simplest way is using array inline and for that the description under <property-name> should work:

components:
  schemas:
    <success-reponse-schema-name>:
      type: object
      properties:
        <property-name>:
          description: <description>
          type: array
          $ref: "#/components/schemas/<schema-array-item>"
...
    <schema-array-item>:
        description: <description>
        type: string

The example is in - Device reachability status API Redoc - I modified it to follow this template

• Case B2 when array is reusable - here the description at array level seems to work in Redoc, the description on items level is not visible in Redoc

components:
  schemas:
    <success-reponse-schema-name>:
      type: object
      properties:
        <property-name>:
          $ref: "#/components/schemas/<schema-array-name>"
...
    <schema-array-name>:
      type: array
      description: <description>
      items:
        type: string
        description: <description>

The example with the same Device reachability status API Redoc - different branch

In summary:

• we need to document Case A,
• case B/B1 is strightforward (we already have requirement to add description to each schema, it should work)
• case C can be seen as over-engineered introducing intermediate array schema

If needed we can think of guidelines for array schema definitions in 5.8.1. WDYT? I am sorry for so late remarks.

To me is fine. I make adjustements. We can document Case A for now

[rartych]

LGTM