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 !
You are mistaken. Swagger will respect any valid v4 JSON schema, as long as it only uses the supported subset.
It goes on to list the parts of JSON schema which are supported, and the bits which are not, and the bits which are extended by swagger.
You can directly goto https://bikcrum.github.io/Swagger-JSON-Schema-In-YAML_webversion/ for online conversion.
I wrote following python script to generate JSON schema in YAML format (preserving key order) that is used in Swagger.
Update: If you want YAML with sorted keys (which is by default) use YAML library
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):
it generated this: