Swagger UI Does not identify definitions data type in the API documentaton window

[steve165]

Using the swagger UI to create a swagger.yaml with a couple of complex objects. When looking at the API documentation, the type is not identified. The yaml below produced the following API documentation that did not identify the data type. It identified object in the array simply as an object and of the type referenced by the GET response schema.

Is this just an API documentation fault?

swagger: 2.0
info:
version: "0.0.1"
title: glh 'ideal' open API

during dev, should point to your local machine

host: api.glhhotels.com

basePath prefixes all resource paths

basePath: /

schemes:

tip: remove http to make production-grade

• http
• https

  format of bodies a client can send (Content-Type)

  consumes:
• application/json

  format of the responses to the client (Accepts)

  produces:
• application/json
  x-volos-resources: {}
  paths:
  /preferences/{preferenceCode}:

  binds a127 app logic to a route

  x-swagger-router-controller: preferencesController
  x-volos-authorizations: {}
  x-volos-apply: {}
  get:
  description: Returns the collection of preference codes and descriptions
  # used as the method name of the controller
  operationId: getPreferences
  parameters:
  - name: preferenceCode
  in: path
  description: An individual preference code. Add to limit the response to a single specific preference.
  required: false
  type: string
  responses:
  "200":
  description: Success
  schema:
  # a pointer to a definition
  $ref: PreferencesGetResponse
  # responses may fall through to errors
  default:
  description: Error
  schema:
  $ref: StatusResponse

definitions:

StatusResponse:
required:
- statusCode
- statusDetails
properties:
statusCode:
type: string
statusDetails:
type: string
moreInfo:
type: array
items: {"label": string, "link": string}

Preference model

PreferenceDetails:
required:
- preferenceType
- preferenceValue
properties:
preferenceTyoe:
type: string
preferenceDescription:
type: string
preferenceValue:
type: string
preferenceNotes:
type: string

PreferencesGetResponse:
required:
- status
- list
properties:
status:
type: object
$ref: StatusResponse
list:
type: array
items: {"object": "PreferenceDetails"}

[steve165]

Here's the uncorrupted yaml text

swagger: 2.0
info:
  version: "0.0.1"
  title: glh 'ideal' open API 
# during dev, should point to your local machine
host: api.glhhotels.com
# basePath prefixes all resource paths 
basePath: /
# 
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
x-volos-resources: {}
paths:
  /preferences/{preferenceCode}:
    # binds a127 app logic to a route
    x-swagger-router-controller: preferencesController
    x-volos-authorizations: {}
    x-volos-apply: {}
    get:
      description: Returns the collection of preference codes and descriptions
      # used as the method name of the controller
      operationId: getPreferences
      parameters:
        - name: preferenceCode
          in: path
          description: An individual preference code. Add to limit the response to a single specific preference.
          required: false
          type: string
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: PreferencesGetResponse
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: StatusResponse 

definitions:

#
  StatusResponse:
    required:
      - statusCode
      - statusDetails
    properties:
      statusCode:
        type: string
      statusDetails:
        type: string
      moreInfo:
        type: array
        items: {"label": string, "link": string}

###################################################################################
#       Preference model   
#
###################################################################################

  PreferenceDetails:
    required:
      - preferenceType
      - preferenceValue
    properties:
      preferenceTyoe:
        type: string
      preferenceDescription:
        type: string
      preferenceValue:
        type: string
      preferenceNotes:
        type: string

  PreferencesGetResponse:
    required:
      - status
      - list
    properties:
      status:
        type: object
        $ref: StatusResponse
      list:
        type: array
        items: {"object": "PreferenceDetails"}

[webron]

This is actually swagger-editor and not swagger-ui so in the future you'd want open the issue there.

Specifically for your case, your YAML is malformed when it comes to the items part.

For example, PreferencesGetResponse should look like this:

  PreferencesGetResponse:
    required:
      - status
      - list
    properties:
      status:
        type: object
        $ref: StatusResponse
      list:
        type: array
        items: 
          $ref: PreferenceDetails

[steve165]

Thanks webron that fixed that instance. Can you point me to where this is defined in the swagger spec or yaml spec,

[webron]

I admit it is not thoroughly described in the spec since it is based off on the json-schema definition. You can read more about it here - https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#schemaObject

[steve165]

No probs thanks for your help

On Thursday, October 9, 2014, webron notifications@github.com wrote:

I admit it is not thoroughly described in the spec since it is based off
on the json-schema definition. You can read more about it here -
https://github.com/wordnik/swagger-spec/blob/master/versions/2.0.md#schemaObject

—
Reply to this email directly or view it on GitHub
#652 (comment).