widdershins: Missing example response

Input swagger.json:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "This is documentation of my API",
    "version" : "0.3",
    "title" : "My API"
  },
  "host" : "my.url.com",
  "tags" : [ {
    "name" : "Somethings",
    "description" : "Endpoint for managing somethings"
  } ],
  "schemes" : [ "https" ],
  "paths" : {
    "/api/somethings" : {
      "get" : {
        "tags" : [ "Events" ],
        "summary" : "getSomethings",
        "description" : "Get list of somethings matching query",
        "operationId" : "getSomethings",
        "consumes" : [ "application/json" ],
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "type",
          "in" : "query",
          "description" : "Type of something",
          "required" : false,
          "type" : "string"
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "schema" : {
              "$ref" : "#/definitions/EventResponse"
            }
          }
        },
        "security" : [ {
          "session" : [ ]
        }, {
          "api_key" : [ ]
        } ]
      }
    }
  },
  "securityDefinitions" : { },
  "definitions" : {
    "Event" : {
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int64",
          "description" : "ID given by the API to the event."
        },
        "additionalData" : {
          "description" : "Customizable extra data about the event",
          "$ref" : "#/definitions/JsonElement"
        }
      },
      "description" : "An event represents something."
    },
    "EventResponse" : {
      "type" : "object",
      "properties" : {
        "data" : {
          "$ref" : "#/definitions/List_Event"
        }
      }
    },
    "JsonArray" : {
      "type" : "object",
      "properties" : {
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonElement" : {
      "type" : "object",
      "properties" : {
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonNull" : {
      "type" : "object",
      "properties" : {
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonObject" : {
      "type" : "object",
      "properties" : {
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "JsonPrimitive" : {
      "type" : "object",
      "properties" : {
        "boolean" : {
          "type" : "boolean",
          "default" : false
        },
        "number" : {
          "type" : "boolean",
          "default" : false
        },
        "string" : {
          "type" : "boolean",
          "default" : false
        },
        "asString" : {
          "type" : "string"
        },
        "asDouble" : {
          "type" : "number",
          "format" : "double"
        },
        "asInt" : {
          "type" : "integer",
          "format" : "int32"
        },
        "asBoolean" : {
          "type" : "boolean",
          "default" : false
        },
        "asNumber" : {
          "$ref" : "#/definitions/Number"
        },
        "asFloat" : {
          "type" : "number",
          "format" : "float"
        },
        "asLong" : {
          "type" : "integer",
          "format" : "int64"
        },
        "asByte" : {
          "type" : "string",
          "format" : "byte"
        },
        "asCharacter" : {
          "type" : "string"
        },
        "asBigDecimal" : {
          "type" : "number"
        },
        "asBigInteger" : {
          "type" : "integer"
        },
        "asShort" : {
          "type" : "integer",
          "format" : "int32"
        },
        "jsonArray" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonPrimitive" : {
          "type" : "boolean",
          "default" : false
        },
        "jsonNull" : {
          "type" : "boolean",
          "default" : false
        },
        "asJsonObject" : {
          "$ref" : "#/definitions/JsonObject"
        },
        "asJsonArray" : {
          "$ref" : "#/definitions/JsonArray"
        },
        "asJsonPrimitive" : {
          "$ref" : "#/definitions/JsonPrimitive"
        },
        "asJsonNull" : {
          "$ref" : "#/definitions/JsonNull"
        },
        "jsonObject" : {
          "type" : "boolean",
          "default" : false
        }
      }
    },
    "List_Event" : {
      "type" : "object",
      "properties" : {
        "items" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Event"
          }
        }
      }
    }
  }
}

Output of widdershins swagger.json -o index.html.md:

---
title: My API v0.3
language_tabs:
  - shell: Shell
  - http: HTTP
  - javascript: JavaScript
  - javascript--nodejs: Node.JS
  - ruby: Ruby
  - python: Python
  - java: Java
toc_footers: []
includes: []
search: true
highlight_theme: darkula
---

# My API v0.3

> Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This is documentation of my API

Base URLs:

* <a href="https://my.url.com/">https://my.url.com/</a>





# Events

## getSomethings

> Code samples

/```shell
# You can also use wget
curl -X GET https://my.url.com//api/somethings \
  -H 'Accept: application/json'

/```

/```http
GET https://my.url.com//api/somethings HTTP/1.1
Host: my.url.com

Accept: application/json

/```

/```javascript
var headers = {
  'Accept':'application/json'

};

$.ajax({
  url: 'https://my.url.com//api/somethings',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})
/```

/```javascript--nodejs
const request = require('node-fetch');

const headers = {
  'Accept':'application/json'

};

fetch('https://my.url.com//api/somethings',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});
/```

/```ruby
require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://my.url.com//api/somethings',
  params: {
  }, headers: headers

p JSON.parse(result)
/```

/```python
import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://my.url.com//api/somethings', params={

}, headers = headers)

print r.json()
/```

/```java
URL obj = new URL("https://my.url.com//api/somethings");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());
/```

`GET /api/somethings`

*getSomethings*

Get list of somethings matching query

### Parameters

Parameter|In|Type|Required|Description
---|---|---|---|---|
type|query|string|false|Type of something


> Example responses

/```json
{
  "data": {}
}
/```
### Responses

Status|Meaning|Description|Schema
---|---|---|---|
200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|successful operation|[EventResponse](#schemaeventresponse)

<aside class="warning">
To perform this operation, you must be authenticated by means of one of the following methods:
None, None
</aside>

# Schemas

## Event

<a name="schemaevent"></a>

/```json
{
  "id": 0,
  "additionalData": {}
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
id|integer(int64)|false|ID given by the API to the event.
additionalData|[JsonElement](#schemajsonelement)|false|No description



## EventResponse

<a name="schemaeventresponse"></a>

/```json
{
  "data": {}
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
data|[List_Event](#schemalist_event)|false|No description



## JsonArray

<a name="schemajsonarray"></a>

/```json
{
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonArray": false,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonArray|boolean|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
jsonObject|boolean|false|No description



## JsonElement

<a name="schemajsonelement"></a>

/```json
{
  "jsonArray": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
jsonArray|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonObject|boolean|false|No description



## JsonNull

<a name="schemajsonnull"></a>

/```json
{
  "jsonArray": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
jsonArray|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonObject|boolean|false|No description



## JsonObject

<a name="schemajsonobject"></a>

/```json
{
  "jsonArray": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
jsonArray|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonObject|boolean|false|No description



## JsonPrimitive

<a name="schemajsonprimitive"></a>

/```json
{
  "boolean": false,
  "number": false,
  "string": false,
  "asString": "string",
  "asDouble": 0,
  "asInt": 0,
  "asBoolean": false,
  "asNumber": {},
  "asFloat": 0,
  "asLong": 0,
  "asByte": "string",
  "asCharacter": "string",
  "asBigDecimal": 0,
  "asBigInteger": 0,
  "asShort": 0,
  "jsonArray": false,
  "jsonPrimitive": false,
  "jsonNull": false,
  "asJsonObject": {},
  "asJsonArray": {},
  "asJsonPrimitive": {},
  "asJsonNull": {},
  "jsonObject": false
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
boolean|boolean|false|No description
number|boolean|false|No description
string|boolean|false|No description
asString|string|false|No description
asDouble|number(double)|false|No description
asInt|integer(int32)|false|No description
asBoolean|boolean|false|No description
asNumber|[](#schema)|false|No description
asFloat|number(float)|false|No description
asLong|integer(int64)|false|No description
asByte|string(byte)|false|No description
asCharacter|string|false|No description
asBigDecimal|number|false|No description
asBigInteger|integer|false|No description
asShort|integer(int32)|false|No description
jsonArray|boolean|false|No description
jsonPrimitive|boolean|false|No description
jsonNull|boolean|false|No description
asJsonObject|[JsonObject](#schemajsonobject)|false|No description
asJsonArray|[JsonArray](#schemajsonarray)|false|No description
asJsonPrimitive|[JsonPrimitive](#schemajsonprimitive)|false|No description
asJsonNull|[JsonNull](#schemajsonnull)|false|No description
jsonObject|boolean|false|No description



## List_Event

<a name="schemalist_event"></a>

/```json
{
  "items": [
    {}
  ]
} 
/```

### Properties

Name|Type|Required|Description
---|---|---|---|
type|Unknown|false|No description
items|[Event](#schemaevent)|false|No description
x-isArray|Unknown|false|No description
$ref|Unknown|false|No description

What I expect to see is a response body, not a data field with an empty object. Is there are problem when widdershins is parsing JsonElement that causes everything else in my Event class to disappear? Because even though I add other fields they don’t appear unless I remove the JsonElement field.

About this issue

  • Original URL
  • State: closed
  • Created 7 years ago
  • Comments: 19 (10 by maintainers)

Most upvoted comments

Why is this closed?

Closing this now as v3.0.0 includes completely different dereferencing and schema extraction algorithms.

Bottom line Widdershins fails to generate example responses markdown.

Fine. Fix the attitude or use some other tool.

+2
MikeRalphson on Dec 2, 2018

Hi @MikeRalphson,

Is it possible to custom the response example? I want it to be like what it show on swagger ( like the picture shown below ) right example

what I get now: not expected example

Thanks!

+1
Eileen0917 on Apr 25, 2019

Sorry, perhaps we both had suboptimal days? Apologies.

+1
MikeRalphson on Dec 9, 2018
Read more comments on GitHub
← oas-kit: YAML output missing quotations around examples
widdershins: RangeError when using widdershins with a new OpenApi v3 spec file →