Convert JSON to JSON Schema draft 4 compatible with Swagger 2.0

Cwellan picture Cwellan · Dec 1, 2016 · Viewed 24.9k times · Source

I've been given some JSON files generated by a REST API with plenty of properties.

I've created a Swagger 2.0 definition for this API and need to give it the corresponding schema for the response.

The main problem: this JSON file has loads of properties. It would take so much time and I would make many mistakes if I write the schema manually. And it’s not the only API I need to describe.

I know there are some tools to convert JSON to JSON schemas but, if I’m not mistaken, Swagger only has $refs to other objects definitions thus only has one level whereas the tools I’ve found only produce tree structured schemas. My question: is there any tool to convert a JSON (or JSON Schema) to a Swagger 2.0 compatible one ?

Note: I'm working in YAML but I wouldn't be an issue, would it ?

For example, what I need:

  List of Movements:
    type: "array"
    items:
      $ref: "#/definitions/Movement"
  Movement:
    properties:
      dateKey:
        type: "string"
      movement:
        $ref: "#/definitions/Stock"
    additionalProperties: false
  Stock:
    properties:
      stkUnitQty:
        type: "string"
      stkDateTime:
        type: "string"
      stkUnitType:
        type: "string"
      stkOpKey:
        type: "string"
    additionalProperties: false

For my JSON document:

[
  {
    "dateKey": "20161110",
    "stkLvls": [
      {
        "stkOpKey": "0",
        "stkUnitType": "U",
        "stkDateTime": "20161110T235010.240+0100",
        "stkUnitQty": 30
      }
    ]
  },
  {
    "dateKey": "20161111",
    "stkLvls": [
      {
        "stkOpKey": "0",
        "stkUnitType": "U",
        "stkDateTime": "20161111T231245.087+0100",
        "stkUnitQty": 21
      }
    ]
  }
  ]

But, what http://jsonschema.net/#/ gives me:

---
"$schema": http://json-schema.org/draft-04/schema#
type: array
items:
  type: object
  properties:
    dateKey:
      type: string
    stkLvls:
      type: array
      items:
        type: object
        properties:
          stkOpKey:
            type: string
          stkUnitType:
            type: string
          stkDateTime:
            type: string
          stkUnitQty:
            type: integer
        required:
        - stkOpKey
        - stkUnitType
        - stkDateTime
        - stkUnitQty
  required:
  - dateKey
  - stkLvls

I'm new to that, but curious, don't hesitate to explain deeply.

Thank you in advance for your help !

Answer

mateuscb picture mateuscb · Jun 14, 2017

I also needed a converter tool and came across this. So far it seems to work pretty well. It does both JSON and YAML formats.

https://swagger-toolbox.firebaseapp.com/

Given this JSON (their sample):

{
  "id": 1,
  "name": "A green door",
  "price": 12,
  "testBool": false,
  "tags": [
    "home",
    "green"
  ]
}

it generated this:

{
    "required": [
        "id",
        "name",
        "price",
        "testBool",
        "tags"
    ],
    "properties": {
        "id": {
            "type": "number"
        },
        "name": {
            "type": "string"
        },
        "price": {
            "type": "number"
        },
        "testBool": {
            "type": "boolean"
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
}