Simple Swagger.v2 array definition not responding

Question

Am trying to learn swagger. To create a mock server for a simple api that returns

A) an object of the form {id: someid, name: some name}

b) an array of those object

I have the first part working but the second just won't work. Can someone who knows have a look at my YAML definition below ?

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - http
host: localhost:8080
basePath: /

Here are the two paths defined, the first (/api/dataset) works, the second (/api/datasets) does not.

paths:
  /api/dataset: 
    get:
      summary: summary
      description: desc
      responses:
        200:
          description: dataset
          schema:
            $ref: '#/definitions/dataset'

  /api/datasets: 
    get:
      summary: summary
      description: desc
      responses:
        200:
          description: datasets list
          schema:
            $ref: '#/definitions/datasets'

These are the definitions, I suspect I'm doing something wrong here ...

definitions:
  dataset:
    type: object
    properties:
      dataset_id:
        type: string
      name:
        type: string
    required: 
      - dataset_id
      - name
    example:
      dataset_id: FunnyJokesData
      name: FunnyJokesData
  datasets:
    type: array
    items: 
      $ref: '#/definitions/dataset'
    example:
      - dataset_id: example_01
        name: example_01
      - dataset_id: example_02
        name: example_02
      - dataset_id: example_03
        name: example_03

After generating a stub server with this definition the curl response for /api/dataset has a response body:

$ curl -X GET "http://localhost:8080/api/dataset" -H "accept: application/json" % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 64 0 64 0 0 4000 0 --:--:-- --:--:-- --:--:-- 4000{ "dataset_id": "FunnyJokesData", "name": "FunnyJokesData" }

but the curl response for '/api/datasets' is empty:

$ curl -X GET "http://localhost:8080/api/datasets" -H "accept: application/json" % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0

I can't figure out why one works and the other does not.

thanks for looking

Answer 1

I guess "won't work" applies just to the Node.js server stub, because the Python/Flask stub returns the string "do some magic!" instead of JSON for both endpoints.

It looks like Swagger Codegen's Node.js generator does not support array-level example, that's why the corresponding response is empty. You can submit a bug report here: https://github.com/swagger-api/swagger-codegen/issues.

One workaround that seems to be working with the Node.js generator is to use response examples instead:

  /api/datasets: 
    get:
      summary: summary
      description: desc
      responses:
        200:
          description: datasets list
          schema:
            $ref: '#/definitions/datasets'

          examples:
            application/json:
              - dataset_id: example_01
                name: example_01
              - dataset_id: example_02
                name: example_02
              - dataset_id: example_03
                name: example_03