Skip to content

Commit f6af553

Browse files
JaredCEJaredCE
authored
Merge pull request #20 from JaredCE/test-rewrites
Rewrite of library Removes de-referencing, now expects user to use a library to handle de-referencing Simplifies code
2 parents f99bd6a + d2765ed commit f6af553

38 files changed

+2039
-838
lines changed

‎README.md

Lines changed: 198 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,117 +1,233 @@
1-
![example workflow](https://github.com/JaredCE/json-schema-to-openAPI-schema-object/actions/workflows/node.js.yml/badge.svg)
1+
![Node.js CI](https://github.com/JaredCE/json-schema-to-openAPI-schema-object/actions/workflows/node.js.yml/badge.svg)
2+
![version](https://img.shields.io/npm/v/json-schema-for-openapi.svg?style=flat-square)
23

34

4-
# json-schema-to-openAPI-schema-object
5+
# json-schema-for-openapi
56

6-
Converts a standard JSON Schema to a compatible Open API v3 Schema Object
7+
Converts a standard [JSON Schema](https://json-schema.org/understanding-json-schema/index.html) to a compatible [OpenAPI v3.0.X Schema Object](https://spec.openapis.org/oas/v3.0.3#schema-object).
78

8-
A json schema with definitions can be converted to an OpenAPI components object containing the main schema and the definitions:
9+
As of version 0.3.0, it is now advised to run a schema through a de-referencer like: https://apitools.dev/json-schema-ref-parser/ to properly deal with `$ref`. I have removed my own poor implementation of de-referencing JSON schemas since there are libraries that can do it better than I can.
910

10-
**simple.schema.json**
11-
```
11+
It should be noted, that de-referencing libraries have their own issues and might not be able to properly parse your JSON/output a schema you might expect. Due to the way OpenAPI v3.0.X Schema Object's are handled, should the referencing not be 100% correct you might face issues using this library and it's output to be used with OpenAPI 3.0.X.
12+
13+
## Conversions
14+
15+
This attempts to massage the standard JSON Schema to a compatible OpenAPI v3.0.X Schema Object. There are many properties that are not supported by OpenAPI v3.0.X Schema Object, though have now been supported by [OpenAPI v3.1.X](https://spec.openapis.org/oas/v3.1.0#schema-object). This library should only be used if working with OpenAPI v3.0.X.
16+
17+
### Items as an Array to Object
18+
19+
This will convert a schema of:
20+
```json
1221
{
13-
"$schema": "http://json-schema.org/draft-04/schema#",
14-
"title": "JSON API Schema",
15-
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
1622
"type": "object",
17-
"required": [
18-
"errors"
19-
],
2023
"properties": {
21-
"errors": {
22-
"type": "object",
23-
"properties": {
24-
"message": {
25-
"allOf": [
26-
{
27-
"$ref": "#/definitions/message"
28-
}
29-
]
24+
"example": {
25+
"type": "array",
26+
"items": [
27+
{
28+
"type": "string"
3029
}
30+
]
31+
}
32+
}
33+
}
34+
```
35+
36+
To:
37+
38+
```json
39+
{
40+
"type": "object",
41+
"properties": {
42+
"example": {
43+
"type": "array",
44+
"items": {
45+
"type": "string"
3146
}
3247
}
33-
},
34-
"definitions": {
35-
"message": {
36-
"type": "string"
48+
}
49+
}
50+
```
51+
52+
At the moment, this library cannot handle more than one item in the array, and so will default to using the first item only.
53+
54+
### Types in an array to OneOf
55+
56+
This will convert a schema of:
57+
58+
```json
59+
{
60+
"type": "object",
61+
"properties": {
62+
"example": {
63+
"type": ["string", "number"],
3764
}
3865
}
3966
}
4067
```
4168

42-
This will return an object:
69+
To:
4370

71+
```json
72+
{
73+
"type": "object",
74+
"properties": {
75+
"example": {
76+
"oneOf": [
77+
{
78+
"type": "string"
79+
},
80+
{
81+
"type": "number"
82+
}
83+
]
84+
}
85+
}
86+
}
4487
```
88+
89+
Where an array contains `null`, it will now set `nullable` against all types:
90+
91+
```json
4592
{
46-
schemas: {
47-
message: {
48-
"type": "string"
93+
"type": "object",
94+
"properties": {
95+
"example": {
96+
"type": ["string", "number", "null"],
97+
}
4998
}
50-
main: {
51-
"title": "JSON API Schema",
52-
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
53-
"type": "object",
54-
"required": [
55-
"errors"
56-
],
57-
"properties": {
58-
"errors": {
59-
"type": "object",
60-
"properties": {
61-
"message": {
62-
"allOf": [
63-
{
64-
"$ref": "#/components/schemas/message"
65-
}
66-
]
67-
}
68-
}
69-
}
70-
}
99+
}
100+
```
101+
102+
To:
103+
104+
```json
105+
{
106+
"type": "object",
107+
"properties": {
108+
"example": {
109+
"oneOf": [
110+
{
111+
"type": "string",
112+
"nullable": true
113+
},
114+
{
115+
"type": "number",
116+
"nullable": true
117+
}
118+
]
119+
}
71120
}
72-
}
73121
}
74122
```
75123

76-
To run:
124+
### Const to enum
77125

126+
This will convert a schema of:
127+
128+
```json
129+
{
130+
"type": "object",
131+
"properties": {
132+
"example": {
133+
"type": "string",
134+
"const": "Surburbia"
135+
}
136+
}
137+
}
78138
```
79-
const jsonSchema = require('simple.json.schema')
80-
const ConvertorFactory = require('index')
81139

82-
const convertedSchema = ConvertorFactory.convert(jsonSchema)
140+
To:
141+
142+
```json
143+
{
144+
"type": "object",
145+
"properties": {
146+
"example": {
147+
"type": "string",
148+
"enum": ["Surburbia"]
149+
}
150+
}
151+
}
83152
```
84153

85-
If you already have a referenced schema named "main", it will append a uuid to "main" like thus:
154+
### null types
86155

156+
OpenAPI 3.0.X does not allow for null as a type, so will convert a schema of:
157+
158+
```json
159+
{
160+
"type": "object",
161+
"properties": {
162+
"example": {
163+
"type": "null",
164+
}
165+
}
166+
}
87167
```
168+
169+
To:
170+
171+
```json
88172
{
89-
schemas: {
90-
main: {
91-
"type": "string"
173+
"type": "object",
174+
"properties": {
175+
"example": {
176+
"nullable": true,
177+
}
178+
}
179+
}
180+
```
181+
182+
### Default to their type
183+
184+
This will convert the `"default":` value to the relevant type. A String to a String, a Number/Integer to a number/Integer, a Boolean to a Boolean and try to manipulate an Object or an Array to either an Object or an Array
185+
186+
### Dependencies, DependentRequired, DependentSchemas
187+
188+
This will try to convert `"dependencies":`, `"dependentRequired":` and `"dependentSchemas":` to a valid `"allOf"` in the case of a `"dependentSchemas"` or an `"anyOf":` schema in the case of a `"dependentRequired"`.
189+
190+
### If/Then/Else
191+
192+
It will try to convert an If/Then/Else schema statement to a valid `"OneOf"` schema.
193+
194+
## Installation and Usage:
195+
196+
Install via npm: `npm install json-schema-for-openapi`.
197+
198+
And use as a Factory like:
199+
200+
```js
201+
const ConvertorFactory = require('json-schema-for-openapi')
202+
const jsonSchema = {
203+
"$schema": "http://json-schema.org/draft-04/schema#",
204+
"title": "JSON API Schema",
205+
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
206+
"type": "object",
207+
"properties": {
208+
"errors": {
209+
"type": "object"
210+
}
92211
}
93-
"main-547d55a5-87e9-444e-8783-e64f6863d20e": {
94-
"title": "JSON API Schema",
95-
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
96-
"type": "object",
97-
"required": [
98-
"errors"
99-
],
100-
"properties": {
101-
"errors": {
102-
"type": "object",
103-
"properties": {
104-
"message": {
105-
"allOf": [
106-
{
107-
"$ref": "#/components/schemas/main"
108-
}
109-
]
110-
}
111-
}
112-
}
113-
}
212+
}
213+
const convertedSchema = ConvertorFactory.convert(jsonSchema, 'main')
214+
```
215+
216+
which will output:
217+
218+
```json
219+
{
220+
"schemas": {
221+
"main": {
222+
"title": "JSON API Schema",
223+
"description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
224+
"type": "object",
225+
"properties": {
226+
"errors": {
227+
"type": "object"
228+
}
229+
}
230+
}
114231
}
115-
}
116232
}
117-
```
233+
```

0 commit comments

Comments
 (0)