Skip to content

Commit 15cde83

Browse files
pileroupilerou
committed
� Conflicts: � src/framework/ajv/index.ts � src/framework/types.ts � src/openapi.validator.ts
2 parents e08f45a + eb33717 commit 15cde83

File tree

12 files changed

+2365
-33
lines changed

12 files changed

+2365
-33
lines changed

‎README.md

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -495,7 +495,8 @@ OpenApiValidator.middleware({
495495
fileUploader: { ... } | true | false,
496496
$refParser: {
497497
mode: 'bundle'
498-
}
498+
},
499+
schemaObjectMapper: { ... }
499500
});
500501
```
501502

@@ -621,6 +622,56 @@ Determines whether the validator should validate responses. Also accepts respons
621622
}
622623
}
623624
```
625+
626+
627+
### ▪️ schemaObjectMapper (optional)
628+
Maps specified schema objects to custom `deserialize` and `serialize` functions. Example use cases include:
629+
630+
- automatically convert a `string` to/from a `Date`
631+
- automatically convert a `string` to/from a MongoDb `ObjectId`
632+
- ...
633+
634+
The `schemaObjectMapper` is an object. Each of its keys must match the name of a declared Schema Object. The value of each key must contain a `deserialize` and `serialize` function
635+
636+
- `deserialize` - a custom function that converts a string value (provided in a request) to an in-memory representation. For example, one might define `deserialize` to convert the string `2020-12-12` to a `Date`.
637+
638+
- `serialize` - a custom function that converts an in-memory representation to a string (sent in the response). For example, one might define `serialize` to convert the object `new Date('2020-12-20')` to a string, `2020-12-20T00:00:00.000Z`.
639+
640+
For example,
641+
642+
```javascript
643+
schemaObjectMapper: {
644+
'ObjectId': {
645+
deserialize: (o) => new ObjectID(o),
646+
serialize: (o) => o.toString(),
647+
},
648+
'Date': {
649+
deserialize: (o) => new Date(o),
650+
serialize: (o) => o.toISOString().slice(0, 10),
651+
},
652+
'DateTime': {
653+
deserialize: (o) => new Date(o),
654+
serialize: (o) => o.toISOString(),
655+
}
656+
}
657+
```
658+
659+
Each 'schema object' mapping key must be declared in `components.schemas`.
660+
661+
```yaml
662+
components:
663+
schemas:
664+
ObjectId:
665+
type: string
666+
pattern: '^[0-9a-fA-F]{24}$'
667+
Date:
668+
type: string
669+
format: date
670+
DateTime:
671+
type: string
672+
format: date-time
673+
```
674+
See a complete example [here](examples/7-schema-object-mapper).
624675
625676
### ▪️ validateSecurity (optional)
626677

‎examples/7-schema-object-mapper/README.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# example
2+
3+
The `schemaObjectMapper` option enables the use of a custom serializer and deserializer for explicitly declared schema objects.
4+
5+
Using `schemaObjectMapper`, one can deserialize a string value received in a request and convert it to an object. For example, you might convert a string representing a date to a `Date` object. Furthermore, one must also define its serializer. For example, converting a `Date` object to a string. The string representation is then sent in the response.
6+
7+
Some common use cases include:
8+
- converting a string to/from `Date`
9+
- converting a string to/from a MongoDb `ObjectId`
10+
11+
## Install
12+
13+
```shell
14+
npm run deps && npm i
15+
```
16+
17+
## Run
18+
19+
From this `7-schema-object-mapper` directory, run:
20+
21+
```shell
22+
npm start
23+
```
24+
25+
## Try
26+
27+
```shell
28+
29+
## call pets
30+
## the call below should return 400 since it requires additional parameters
31+
curl http://localhost:3000/v1/pets?type=dog&limit=3
32+
33+
## Get the first item id
34+
curl http://localhost:3000/v1/pets/<first item id>
35+
```

‎examples/7-schema-object-mapper/api.yaml

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
openapi: '3.0.0'
2+
info:
3+
version: 1.0.0
4+
title: Swagger Petstore schemaObjectMapper variant
5+
description: A sample API
6+
termsOfService: http://swagger.io/terms/
7+
license:
8+
name: Apache 2.0
9+
url: https://www.apache.org/licenses/LICENSE-2.0.html
10+
servers:
11+
- url: /v1
12+
paths:
13+
/ping:
14+
get:
15+
description: |
16+
ping then pong!
17+
operationId: ping
18+
responses:
19+
'200':
20+
description: OK
21+
content:
22+
text/plain:
23+
schema:
24+
type: string
25+
example: pong
26+
default:
27+
description: unexpected error
28+
content:
29+
application/json:
30+
schema:
31+
$ref: '#/components/schemas/Error'
32+
/pets:
33+
get:
34+
description: |
35+
Returns all pets
36+
operationId: findPets
37+
parameters:
38+
- name: type
39+
in: query
40+
description: maximum number of results to return
41+
required: true
42+
schema:
43+
type: string
44+
enum:
45+
- dog
46+
- cat
47+
- name: tags
48+
in: query
49+
description: tags to filter by
50+
required: false
51+
style: form
52+
schema:
53+
type: array
54+
items:
55+
type: string
56+
- name: limit
57+
in: query
58+
description: maximum number of results to return
59+
required: true
60+
schema:
61+
type: integer
62+
format: int32
63+
minimum: 1
64+
maximum: 20
65+
responses:
66+
'200':
67+
description: pet response
68+
content:
69+
application/json:
70+
schema:
71+
type: array
72+
items:
73+
$ref: '#/components/schemas/Pet'
74+
default:
75+
description: unexpected error
76+
content:
77+
application/json:
78+
schema:
79+
$ref: '#/components/schemas/Error'
80+
81+
post:
82+
description: Creates a new pet in the store.
83+
operationId: addPet
84+
security:
85+
- ApiKeyAuth: []
86+
requestBody:
87+
description: Pet to add to the store
88+
required: true
89+
content:
90+
application/json:
91+
schema:
92+
$ref: '#/components/schemas/Pet'
93+
responses:
94+
'200':
95+
description: pet response
96+
content:
97+
application/json:
98+
schema:
99+
$ref: '#/components/schemas/Pet'
100+
default:
101+
description: unexpected error
102+
content:
103+
application/json:
104+
schema:
105+
$ref: '#/components/schemas/Error'
106+
107+
/pets/{id}:
108+
get:
109+
description: Returns a user based on a single ID, if the user does not have access to the pet
110+
operationId: find pet by id
111+
parameters:
112+
- name: id
113+
in: path
114+
description: ID of pet to fetch
115+
required: true
116+
schema:
117+
$ref: '#/components/schemas/ObjectId'
118+
responses:
119+
'200':
120+
description: pet response
121+
content:
122+
application/json:
123+
schema:
124+
$ref: '#/components/schemas/Pet'
125+
default:
126+
description: unexpected error
127+
content:
128+
application/json:
129+
schema:
130+
$ref: '#/components/schemas/Error'
131+
delete:
132+
description: deletes a single pet based on the ID supplied
133+
operationId: deletePet
134+
parameters:
135+
- name: id
136+
in: path
137+
description: ID of pet to delete
138+
required: true
139+
schema:
140+
$ref: '#/components/schemas/ObjectId'
141+
responses:
142+
'204':
143+
description: pet deleted
144+
default:
145+
description: unexpected error
146+
content:
147+
application/json:
148+
schema:
149+
$ref: '#/components/schemas/Error'
150+
151+
/pets/{id}/photos:
152+
post:
153+
description: upload a photo of the pet
154+
operationId: uploadPetPhoto
155+
parameters:
156+
- name: id
157+
in: path
158+
description: ID of pet to fetch
159+
required: true
160+
schema:
161+
$ref: '#/components/schemas/ObjectId'
162+
requestBody:
163+
content:
164+
multipart/form-data:
165+
schema:
166+
# $ref: '#/components/schemas/NewPhoto'
167+
type: object
168+
required:
169+
- file
170+
properties:
171+
file:
172+
description: The photo
173+
type: string
174+
format: binary
175+
required: true
176+
responses:
177+
201:
178+
description: Created
179+
content:
180+
application/json:
181+
schema:
182+
type: object
183+
properties:
184+
success:
185+
type: boolean
186+
187+
components:
188+
schemas:
189+
ObjectId:
190+
type: string
191+
pattern: '^[0-9a-fA-F]{24}$'
192+
Date:
193+
type: string
194+
format: date
195+
DateTime:
196+
type: string
197+
format: date-time
198+
Pet:
199+
required:
200+
- id
201+
- name
202+
- type
203+
properties:
204+
id:
205+
$ref: '#/components/schemas/ObjectId'
206+
name:
207+
type: string
208+
tag:
209+
type: string
210+
type:
211+
$ref: '#/components/schemas/PetType'
212+
creationDate:
213+
$ref: '#/components/schemas/DateTime'
214+
215+
PetType:
216+
type: string
217+
enum:
218+
- dog
219+
- cat
220+
221+
Error:
222+
required:
223+
- code
224+
- message
225+
properties:
226+
code:
227+
type: integer
228+
format: int32
229+
message:
230+
type: string
231+
232+
securitySchemes:
233+
ApiKeyAuth:
234+
type: apiKey
235+
in: header
236+
name: X-API-Key

0 commit comments

Comments
 (0)