Redoc: Wrong description on same nested schema properties.

Created on 6 Jun 2019 · 3Comments · Source: Redocly/redoc

Setup: Same named properties have different meaning in our model, hence come with a different description in our schema. ReDoc displays the parents property's description on any nested occurrences. I have striped everything from our project to get a minimal example. In our project it actually goes even 3 levels deep.

Files:

index.html:

<!DOCTYPE html>
<html>

<head>
  <title>ReDoc</title>
  <!-- needed for adaptive design -->
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

  <!--
    ReDoc doesn't change outer page styles
    -->
  <style>
    body {
      margin: 0;
      padding: 0;
    }
  </style>
</head>

<body>
  <!-- <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc> -->
  <redoc spec-url='/openapi.yml'></redoc>
  <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>

</html>

openapi.yml:

openapi: 3.0.0
info:
  title: Deployed APIs
  version: 1.0.0
servers:
- url: http://ebalance-test-api.sloppy.zone/backend

paths:
  /menuplans/{id}:
    get:
      operationId: Get Menuplan by ID
      responses:
        200:
          description: default response
          content:
            application/json:
              schema: 
                $ref: '/schemas/menuplan.yml'

schemas/menuplan.yml

$schema: http://json-schema.org/draft-07/schema
id: menuplan
type: object
properties:
  id: 
    type: string
  nutritions: 
    description: AAA Sum  of all meal's nutritions for this plan. 
    $ref: 'nutritions.yml'
  breakfast:     
    $ref: 'meal.yml'
  lunch: 
    $ref: 'meal.yml'
  dinner: 
    $ref: 'meal.yml'

schemas/meal.yml

$schema: http://json-schema.org/draft-07/schema
id: meal
type: object
properties:
  id: 
    type: string
  nutritions: 
    description: BBB Sum of all nutritions eaten with the meal.
    $ref: 'nutritions.yml'

schemas/nutritions.yml
`$schema: http://json-schema.org/draft-07/schema id: nutritions type: object description: List of all nutritons a food, recipe or meal has. properties: energy: description: energy in kcal type: number format: float protein: description: protein in gram type: number format: float carbohydrates: description: carbohydrates in gram type: number format: float fat: description: fat in gram type: number format: float

Source

martnst

Most helpful comment

Hello @martnst, please try https://stackoverflow.com/questions/29463634/combining-defintions-in-swagger-docs (also you can check https://swagger.io/docs/specification/using-ref/ , at the end)

bossqone on 10 Jun 2019

👍2

All 3 comments

Here is another example, which should look like this in code:

  nutritions: 
    description: Sum of all nutritions of all ingredients
    $ref: 'nutritions.yml'
  nutritionsPerPortion:
    description: Sum of all nutritions of all ingredients per portion
    $ref: 'nutritions.yml'

martnst on 6 Jun 2019

Hello @martnst, please try https://stackoverflow.com/questions/29463634/combining-defintions-in-swagger-docs (also you can check https://swagger.io/docs/specification/using-ref/ , at the end)

bossqone on 10 Jun 2019

👍2

$ref does not merge. You description gets overwritten. Use allOf (see examples in the links by @bossqone)