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

Your spec is correct and is rendered correctly in http://editor.swagger.io. What exactly do you mean by "the first part working but the second just won't work"? — Helen, Jul 23 '18 at 07:35
@Helen, oh yes, it renders. But when I generate a stub server and "try it out" (I tried node and Python flask) there is no response body. I was expecting to see the example rendered for datasets path, it is for the other simple path. — Kickaha, Jul 23 '18 at 09:47
*"There is no response body"* - just in Swagger UI or also if you use `curl`/`wget` to send requests from command line? If the issue is only with Swagger UI, what are the errors in the browser console? (E.g. this might be a [CORS](https://stackoverflow.com/q/51407341/113116) [issue](https://stackoverflow.com/q/45439845/113116)). The more details you provide, the easier it is for others to narrow down what you're seeing. — Helen, Jul 23 '18 at 09:58
Also if you need just a mock and not a complete server check out [Swagger mock server](https://stackoverflow.com/q/38344711/113116) for alternatives. — Helen, Jul 23 '18 at 09:59
@Helen Thanks for the suggestions. I've added the curl respones to my question. . . its not a cors issue ... also I need an offline solution, ... a graceful degrade when no connection is available. — Kickaha, Jul 23 '18 at 11:46

score 1 · Accepted Answer · answered Jul 23 '18 at 12:30

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

Thanks for finding a solution to my problem. That little bit of magic you've provided is much appriciated. — Kickaha, Jul 23 '18 at 13:05

Simple Swagger.v2 array definition not responding

1 Answers1