-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathswagger-js.node.txt
112 lines (106 loc) · 7.2 KB
/
swagger-js.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
┏━━━━━━━━━━━━━━━━┓
┃ SWAGGER-JS ┃
┗━━━━━━━━━━━━━━━━┛
ALTERNATIVES ==> #CLI:
# - OpenAPI:
# (OpenAPI 2.0)
# - swagger-codegen "bash" template (prefered):
# - in Bash/ZSH, based on cURL
# - according to SPEC: operationId, REQ parsing, SECURITY
# - autocompletion
# - CLI documentation and API documentation in Markdown
# - good --help
# - vorpal-openapi:
# - built on top of Vorpal, swagger-parser and swagger-js
# - according to SPEC: operationId, SECURITY
# - autocompletion
# - CLI console
# - good --help
#JavaScript:
# - OpenAPI:
# (OpenAPI 2.0/3.0)
# - swagger-js (prefered):
# - browser/Node (uses CROSS-FETCH)
# - FETCH-like interface
# - resolves JSON references (with own code)
# - according to SPEC: operationId, REQ limited validation, REQ|RES parsing|serializing, SECURITY
# - REQ|RES mocking
# - REQ|RES interceptors, plugins
# (OpenAPI 2.0, soon 3.0)
# - swagger-codegen
# (OpenAPI 2.0)
# - swagger-js-codegen:
# - browser/Node (using FETCH and REQUEST)
# - built from Mustache template
# - according to SPEC: operationId, REQ serializing, SECURITY
# - optional support for TypeScript and Angular
# - openapi-client:
# - not well maintained
# - browser/Node (uses ISOMORPHIC-FETCH)
# - FETCH-like interface
# - resolves JSON references (with own code)
# - according to SPEC: operationId, SECURITY
# - REQ|RES interceptor
# - JSDoc comments
# - created from template
# - swagger-codegen "javascript" template:
# - built from templates
# - Node (uses SUPERAGENT), Browser (require consumer to run BROWSERIFY)
# - according to SPEC: operationId, REQ|RES serializing|parsing, SECURITY
# - generates SDK documentation, JSDoc comments
# - swagger-codegen "typescript-fetch" template:
# - built from templates
# - browser/Node (uses ISOMORPHIC-FETCH)
# - FETCH-like interface
# - according to SPEC: operationId
# - swagger-codegen "typescript-node" template:
# - built from templates
# - Node (uses REQUEST)
# - according to SPEC: operationId
#UI:
# - OpenAPI:
# (OpenAPI 2.0/3.0)
# - swagger-inspector (prefered): SaaS
VERSION ==> #2.1.10-M1
GOAL ==> #Creates JavaScript server-side and client-side from Swagger .json spec (1.2 only), returned as
#API_OBJ.
#API_OBJ can be wrapped/augmented, e.g.:
# - promises instead of callbacks (Bluebird)
# - caching system
# - easier authentication
GLOBAL #Either SWAGGER-CLIENT (server-side) or WINDOW (client-side)
GLOBAL.authorizations.add #Adds Authentication for discovery calls and following API calls, where AUTH can be:
(VAR, AUTH) # - query|header: new GLOBAL.ApiKeyAuthorization(VAR2, VAL2, "query|header")
GLOBAL.authorizations.remove # - cookie: new GLOBAL.CookieAuthorization(COOKIE_OBJ)
(VAR) # - Basic HTTP Authentication: new GLOBAL.PasswordAuthorization(NAME_NOT_USED, USER, PASSWORD)
#VAR is "apiKey|oauth2|basicAuth"
new GLOBAL.SwaggerApi(OBJ) #OBJ:
# - url URL: to the .json spec
# - success FUNC():
# - must then check API_OBJ.ready true
#Returns API_OBJ:
# - basePath, url, info, swaggerVersion, apiVersion, consumes, produces, schemes, host
# - authSchemes MAIN_AUTH_OBJ
# - RESOURCE.NICKNAME(OBJ, FUNC(OBJ2), FUNC2(OBJ3)):
# - use OBJ.body STR for request body (must stringify) and OBJ for headers
# - OBJ2:
# - headers.input|normalized OBJ (normalized put in capital-first dashed)
# - url STR
# - method STR
# - status NUM
# - data BUFFER
# - obj OBJ5
# - OBJ3: for errors. If response from server, like OBJ2. Otherwise:
# - status NUM
# - data BUFFER
# - obj OBJ4:
# - code STR
# - errno STR
# - syscall STR
# - api.RESOURCE.NICKNAME.help(BOOL): returns parameters as print help.
# If BOOL false (def), prints them too.
# - api.RESOURCE.NICKNAME.asCurl(...): same as RESOURCE.NICKNAME(...) but prints Curl shell
# command
#Uses:
# - User-Agent: Shred [C]
# - Right Content-Type, Accept, Content-Length [C]