DapperDox / dapperdox

Beautiful, integrated, OpenAPI documentation.
http://dapperdox.io
GNU General Public License v3.0
409 stars 59 forks source link

Object property examples not displayed #59

Open liborjelinek opened 7 years ago

liborjelinek commented 7 years ago

Definitions with "inline" property example values, i.e. with example along with property, are not displayed in at resource page.

Definition like this

  UserMeResponse:
    type: object
    title: User object
    properties:
      id:
        type: integer
        minimum: 0
        description: User ID.
        example: 2929                 # << property example
      first_name:
        type: string
        description: User's first or given name.
        example: John
      last_name:
        type: string
        description: User's last or family name.
        example: Appleseed
      email:
        type: string
        format: email
        description: User's email.
        example: john@apple.com
      phone:
        type: string
        description: User's phone.
        example: +123 558 951 14
    required:
      - id
      - email

have no example at resource page. But modified to:

  UserMeResponse:
    type: object
    title: User object
    properties:
      id:
        type: integer
        minimum: 0
        description: User ID.
      first_name:
        type: string
        description: User's first or given name.
      last_name:
        type: string
        description: User's last or family name.
      email:
        type: string
        format: email
        description: User's email.
      phone:
        type: string
        description: User's phone.
    required:
      - id
      - email
    example:                # << object example
      id: 2929
      first_name: "John"
      last_name: "Appleseed"
      email: "john@apple.com"
      phone: "+123 558 951 14"

has example section selection_026

IMHO property examples shouldn't be silently loss like now. Other tools, like editor.swagger.io, displays them.

Question is what examples take precedence. Editor.swagger.io overrides property example if there is the object example.

cpage-nexway commented 7 years ago

Agree. Before integrating my swagger into DP, I implemented a routine to fill example at resource level based on what I find at properties level. But it would nice if dapperdox manages that like editor.swagger.io.

zxchris commented 7 years ago

Yup. This is an oversight, the property level example have simply been overlooked. Marking as a bug.

AlexandreRoba commented 7 years ago

Any update on this?