-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathswagger-parser.node.txt
161 lines (143 loc) · 10.3 KB
/
swagger-parser.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
┏━━━━━━━━━━━━━━━━━━━━┓
┃ SWAGGER-PARSER ┃
┗━━━━━━━━━━━━━━━━━━━━┛
VERSION ==> #10.1.1
ALTERNATIVES ==> #See Sway
SWAGGERPARSER.* #Inherits from JSON-SCHEMA-REF-PARSER (i.e. dereferences JSON references)
SwaggerParser|SWAGGERPARSE
.validate(...) #Like REFPARSER.dereference(...) except validates (see below)
POPTS.validate.schema #BOOL (def: true) or custom FUNC(SPEC)
#Validate against official OpenAPI 2.0/3.1 JSON schema (using ajv)
POPTS.validate.spec #BOOL (def: true) or custom FUNC(SPEC)
#Extra checks:
# - very limited check that SCHEMA are valid JSON schemas
# - duplicate PARAM
# - PARAM: multiple body|formData, missing|undeclared path, right MIME with file
┌─────────────────┐
│ SWAGGER-CLI │
└─────────────────┘
SWAGGER-CLI ==> #CLI around Swagger-parser
#Version 4.0.4
swagger-cli validate FILE #Fires SWAGGERPARSER.validate(...) then sets exit code
--no-schema|spec #POPTS.validate.schema|spec false
swagger-cli bundle FILE #Fires SWAGGERPARSER.bundle(...)
-o FILE2
--output FILE2 #Writes JSON file as output
-r
--dereference #Fires SWAGGERPARSER.dereference(...) instead
-f NUM
--format NUM #JSON.stringify() spaces argument (def: 2)
-t|--type json|yaml #Def: 'json'
┌────────────────────────────────┐
│ SWAGGER-EXPRESS-MIDDLEWARE │
└────────────────────────────────┘
SWAGGER-EXPRESS-MIDDLEWARE ==> #Features:
# - validates, assigns default and parses REQ according to PARAM
# - throw 4** when REQ does not match SPEC
# - mock responses according to RESP.headers and RESP.schema.default|example
# - static file serving of OpenAPI specification
# - set current PATHDEF|OPERATION|PARAM|SECURITY_USES to REQ.swagger
# - CORS handling using SPEC
#Based on Swagger-parser
#Version 2.0.2
createMiddleware
([SPEC_OBJ|PATH|URL, ]
[APP, ]FUNC)->SMDW #Calls Middleware(APP).init(SPEC, FUNC)
Middleware([APP])->SMDW #
SMDW.init(SPEC_OBJ|PATH|URL
[, FUNC(ERROR, SMDW, SPEC, #Calls SWAGGERPARSER.dereference(...)
SWAGGERPARSER)]) #Must be called before other methods
SMDW.files([APP, ]OPTS)->MDW_ARR #Express middlewares for:
# - GET /api-docs/:
# - serves bundled OpenAPI specification
# - simply uses RES.json() (no HTTP caching, range requests, etc.)
# - GET /api-docs/*:
# - serves each OpenAPI specification before bundling
# - uses RES.sendFile()
#OPTS:
# - useBasePath BOOL (def: false): prepends SPEC.basePath
# - apiPath STR|false (def: '/api-docs/'): for GET /api-docs/
# - rawFilePath STR|false (def: '/api-docs/'): for GET /api-docs/*
SMDW.metadata([APP])->MDW_ARR #Express middlewares that adds REQ.swagger:
# - api SPEC
# - pathName '/PATH'
# - path PATHDEF
# - operation OPERATION
# - params PARAM_ARR
# - security SECURITY_USES
#According to current URL.
#Nothing is set if current request URL is not under SPEC.basePath.
#Must be used before SMDW.CORS|parseRequest|mock()
SMDW.parseRequest([APP, ]OPTS) #Calls:
->MDW_ARR # - COOKIE-PARSER(OPTS.cookie.secret, OPTS.cookie) (see its doc)
# - BODY-PARSER.json|text|urlencoded|raw(OPTS.json|text|urlencoded|raw) (see its doc)
# - OPTS.limit '1mb' ('5mb' for 'raw')
# - sets OPTS.type
# - OPTS.extended true
# - MULTER(OPTS.multipart) (see its doc)
#For each PARAM:
# - in REQ.query|headers|files|body|pathParams.VAR, REQ.body according to PARAM's [SMALL_]SCHEMA
# - validates (with tv4)
# - assigns SCHEMA.default|example
# - parses from STR to right type
# - including SCHEMA.format|collectionFormat
SMDW.validateRequest()->MDW_ARR #Throw ERRORs:
# - ERROR.status 500: wrong SPEC
# - ERROR.status 401, WWW-Authenticate: Basic realm="HOSTNAME" [S] according to current SECURITY_DEF:
# - basic: no Authorization: Basic [C]
# - apiKey: missing in REQ.headers|query
# - ERROR.status 404: current URL not in SPEC.paths.*
# - ERROR.status 405, Allow [S]: current METHOD not in PATHDEF
# - ERROR.status 406: Accept [C] not in API|OPERATION.produces
# - ERROR.status 413: request body but no body|formData PARAM
# - ERROR.status 415: Content-Type [C] not in API|OPERATION.consumes
SMDW.mock([APP][, STORE]) #Send a mock response according to RESP.headers and RESP.schema.default|example
->MDW_ARR #Based on:
# - RESP according to:
# - RES.statusCode
# - first RESP with priority order: 2**, 3**, default, 4**|5**
# - REQ.method
#Does:
# - if first 2** RESP is array (according to RESP.schema), uses collections
# - GET|HEAD|OPTIONS returns (in priority):
# - empty if RESP.schema true
# - RES.body if set by previous middleware
# - model saved by previous request
# - RESP.schema.default|example
# - POST|PATCH|DELETE|PUT saves REQ
# - PARAM named "file" with target file path
#Identifies resources using MODEL.id|key|code|num[ber]|nbr|[user]name or first required scalar property
#Calls RES.json|send()
#Sets headers:
# - according to RESP.headers
# - value is automatically generated from RESP.headers.NAME.default|schema
# - Content-Type [S] according to SPEC|OPERATION.consumes|produces
# - Location [S], Last-Modified [S], Content-Disposition [S]
# - Set-Cookie [S] randomly generated
#STORE:
# - persists mock data between requests
# - can be:
# - new MemoryDataStore() (def): in-memory
# - new FileDataStore(['DIR']) (def 'DIR': process.cwd())
#Can use:
# - APP.set('mock', false): disables
# - APP.get('mock data store')->STORE
SMDW.CORS()->MDW_ARR #Set CORS response headers (on both preflight requests and final request):
# Access-Control-Allow-Origin: 'ORIGIN|*' [S]
# - using Origin [C]
# Access-Control-Allow-Methods: 'METHOD,...' [S]
# - using OPERATION.*
# - or Access-Control-Request-Method [C]
# - or all possible OpenAPI methods
# Access-Control-Allow-Credentials: true|false [S]
# - false if Access-Control-Allow-Origin: '*'
# Access-Control-Allow-Headers: 'VAL|' [S]
# - using Access-Control-Request-Headers [C]
# Access-Control-Max-Age: 0 [S]
# Vary: Origin [S]
# - unless Access-Control-Allow-Origin '*'
# Any Access-Control-* specified in RESP.headers for current OPERATION or OPTIONS's OPERATION
#On preflight request:
# - calls RES.send()
# - does not set 204 status nor Content-Length: 0 [S] (although should)
#Prefer CORS (see its doc)