-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathsway.node.txt
221 lines (189 loc) · 11.7 KB
/
sway.node.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
┏━━━━━━━━━━┓
┃ SWAY ┃
┗━━━━━━━━━━┛
VERSION ==> #2.0.6
ALTERNATIVES ==> # (OpenAPI 2.0, 3.0)
# - official json schemas:
# - 2.0 is module 'swagger-schema-official'
# - 3.0 are in progress with two competing ones (#1270 and #1236 (aka "gnostic"))
# - both are available in speccy
# - swagger-parser (preferred):
# - dereferences JSON references (with JSON-SCHEMA-REF-PARSER)
# - specification validation: official JSON schema (with z-schema), extra checks
# - oai-ts-core:
# - specification validation: using JavaScript (not official JSON schema) (not enough checks)
# - object model for convenient visiting
# (OpenAPI 3.0)
# - speccy:
# - well maintained
# - dereferences JSON references (with own code)
# - specification validation: official JSON schema (with ajv), many extra checks,
# valid JSON schemas, JSON references
# - specification linting (mostly properties that should not be undefined)
# (OpenAPI 2.0)
# - sway:
# - dereferences JSON references (with JSON-REFS)
# - specification validation: official JSON schema (with z-schema), extra checks,
# valid JSON pointers, valid JSON schemas
# - REQ|RES validation: SPEC|OPERATION.consumes|produces, PARAM|RESP.schema, RESP.headers.NAME
# - REQ parsing and assigning defaults
# - mock data based on RESP|PARAM.schema
# - object model for convenient visiting
# - swagger-express-middleware (prefered if 2.0 or needs static file serving, response mocking):
# - based on swagger-parser (see above)
# - REQ validation: SPEC|OPERATION.consumes|produces, PARAM.schema, PATHDEF, SECURITY_DEF
# - REQ parsing and assigning defaults
# - static file serving of OpenAPI specification
# - mock responses according to RESP.headers and RESP.schema.default|example
# - set current PATHDEF|OPERATION|PARAM|SECURITY_USES to REQ.swagger
# - CORS handling using SPEC
# - swagger-tools:
# - deprecated in favor of sway
# - dereferences JSON references (with JSON-REFS)
# - specification validation: official JSON schema (with z-schema), extra checks
# - REQ|RES validation
# - static file serving of swagger-ui
# - set current PATHDEF|OPERATION|PARAM|SECURITY_USES to REQ.swagger
# - server-side routing based on /PATHs
# - swagger-node-runner:
# - not well maintained
# - mostly convenient wrapper around SWAY
# - also provides with server-side routing, static file serving of OpenAPI specification
# - swagger2:
# - dereferences JSON references (with json-schema-deref-sync)
# - specification validation: official JSON schema (using is-my-json-valid)
# - REQ|RES validation: PARAM|RESP.schema
SWAY.create(OPTS)
->PROMISE_SSPEC #OPTS.definition SPEC|'PATH'|'URL'
SSPEC.options #OPTS
┌────────────────┐
│ TRAVERSING │
└────────────────┘
SSPEC|SPATHDEF|SOPERATION|
SPARAM|SRESP #Wrapper around SPEC|PATHDEF|OPERATION|PARAM|RESP
SSPEC|SPATHDEF|SOPERATION|
SPARAM|SRESP.definition #Underlying SPEC|PATHDEF|OPERATION|PARAM|RESP
SSPEC|SPATHDEF|SOPERATION|
SPARAM|SRESP.* #Same as *.definitionFullyResolved.*
SSPEC.pathObjects|getPaths() #{ '/PATH': SPATHDEF }
SSPEC.getPath('/PATH'|REQ)
->SPATHDEF #Using REQ.originalUrl|url
SPATHDEF.path #'/PATH'
SPATHDEF.api #SSPEC
SSPEC
.getOperations(['/PATH'])
->SOPERATION_ARR #
SSPEC.getOperation
(REQ|'operationId'|'METHOD'|
'/PATH'[, 'METHOD'])
->SOPERATION #Using REQ.method
SPATHDEF.operationObjects|
getOperations() #SOPERATION_ARR
SPATHDEF.getOperation
('operationId'|'METHOD')
->SOPERATION #
SSPEC|SPATHDEF
.getOperationsByTag('TAG')
->SOPERATION_ARR #
SOPERATION.method #'METHOD'
SOPERATION.pathObject #SPATHDEF
SPATHDEF|SOPERATION.
parameterObjects|
getParameters() #SPARAM_ARR
SOPERATION.getParameter
('NAME'[, 'IN'])->SPARAM #
SPARAM.
pathObject|operationObject #SPATHDEF|SOPERATION
SOPERATION.responseObjects|
getResponses() #SRESP_ARR
SOPERATION.getResponse
(['STATUS_CODE'])->SRESP #Def: 'default'
SRESP.statusCode #'STATUS_CODE'
SRESP.operationObject #SOPERATION
┌─────────────────────┐
│ JSON REFERENCES │
└─────────────────────┘
OPTS.jsonRefs #OBJ options to JSON-REFS (see its doc)
#Including OBJ.resolveCirculars BOOL (def: false)
SSPEC|SPATHDEF|SOPERATION|
SPARAM|SRESP.
definitionFullyResolved #Like *.definition but with all JSON references resolved
SSPEC.
definitionRemotesResolved #Like *.definition but with only remote JSON references resolved
SSPEC.references #JSON references
SPATHDEF|SOPERATION|SPARAM|
SRESP.ptr #JSON pointer STR to the property
SPATHDEF|SOPERATION|SPARAM|
SRESP.pathToDefinition #'VAR'_ARR of the property path
┌───────────────────┐
│ NORMALIZATION │
└───────────────────┘
SPATHDEF.regexp #PATH_REGEXP using PATH-TO-REGEXP (see its doc)
SOPERATION.consumes|produces #Using either SPEC|OPERATION.consumes|produces
SOPERATION.parameterObjects|
getParameters() #Using either PATHDEF|OPERATION.parameters (see above)
SPARAM.schema #[SMALL_]SCHEMA
SPARAM.getValue(REQ) #Returns:
->SPARAMVAL # - REQ.body if body PARAM
# - REQ.files.NAME if file PARAM
# - REQ.body.NAME if formData PARAM
# - REQ.headers.NAME if header PARAM
# - REQ.originalUrl|url's part if path PARAM
# - REQ.query.NAME if query PARAM
SPARAMVAL.parameterObject #SPARAM
SPARAMVAL.value #Normalized value:
# - parsed and validated according to PARAM.schema
# - using PARAM.schema.[items.]default if undefined
SPARAMVAL.raw #Value without normalization
SRESP.getExample('MIME')->STR #Same as RESP.examples.MIME but stringified
#(if 'application/json' or 'application/x-yaml')
SOPERATION.getSecurity()
->SECURITY_USES #Using SPEC|OPERATION.security
SOPERATION. #SECURITY_DEF
securityDefinitions.SEC_NAME #SPEC.securityDefinitions.SEC_NAME using SPEC|OPERATION.security
┌────────────────┐
│ VALIDATION │
└────────────────┘
JSON SCHEMA ==> #Uses z-schema
SSPEC.validate()->VALRES #Validates:
# - official JSON schema
# - JSON references
# - SCHEMA are valid JSON schemas
# - duplicate 'PATH'|PARAM|operationId
# - PARAM: empty, multiple body|formData, missing|undeclared path
SOPERATION.validateRequest #Validates:
(REQ[, OPTS])->VALRES # - REQ.headers['content-type'] against SPEC|OPERATION.consumes
# - REQ.body|files|headers|originalUrl|url|query (see SPARAM.getValue()) against PARAM.schema
#OPTS:
# - strictMode BOOL|OBJ: if BOOL true (def: false) or OBJ.formData|header|query BOOL true (def: false), do no allow additionalProperties
SPARAMVAL.valid #BOOL
#Checks according to PARAM.schema|required|allowEmptyValue
SPARAMVAL.error #Same but as ERROR
SOPERATION.validateResponse
(RES[, OPTS])->VALRES #Finds SRESP using RES.statusCode then calls SRESP.validateResponse()
SRESP.validateResponse #Validates:
(RES[, OPTS])->VALRES # - RES.headers['content-type'] against SPEC|OPERATION.produces
# - RES.headers.NAME against RESP.headers.NAME (including collectionFormat)
# - RES.body against RESP.schema
#OPTS:
# - strictMode BOOL|OBJ: if BOOL true (def: false) or OBJ.header BOOL true (def: false), do no allow additionalProperties
VALRES.errors|warnings #VALI_ARR
VALI.code #STR
VALI.error #ERROR
VALI.message #'ERROR'
VALI.errors #Nested VALI_ARR
VALI.path #'VAR'_ARR path to the error property
VALI.lineage #'PATH'_ARR for circular reference errors
VALI.name #Header name STR for header errors
VALI.params #On parameters errors
VALI.schemaId #STR
OPTS|SSPEC.customValidators #FUNC_ARR(SSPEC)->VALRES to add custom validation
#Can also use SSPEC.registerValidator()
OPTS|SSPEC.customFormats #When using custom JSON schema "format"
#Can also use SSPEC.[un]registerFormat()
┌─────────────┐
│ MOCKING │
└─────────────┘
SRESP|SPARAM.getSample()->OBJ #Creates mock data using JSON-SCHEMA-FAKER on RESP|PARAM.schema
OPTS|SSPEC. #When using custom JSON schema "format"
customFormatGenerators #Can also use SSPEC.[un]registerFormatGenerators()