Notes/RPC/Inter_process/API_specification/Generation/OpenAPI/swagger-jsdoc.node_cli.txt at master · dginorg/Notes · GitHub

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

                                  ┏━━━━━━━━━━━━━━━━━━━┓
                                  ┃   SWAGGER-JSDOC   ┃
                                  ┗━━━━━━━━━━━━━━━━━━━┛

ALTERNATIVES ==>              #From code:
                              #  - OpenAPI 2.0:
                              #     - swagger-definer: using imperative FUNC() calls|decorators
                              #From code (framework-specific, i.e. avoid)
                              #  - OpenAPI 2.0:
                              #     - fastify-swagger: as extra OBJ to framework routers FUNC()
                              #     - hapi-swagger: as extra OBJ to framework routers FUNC(). Also guess some from router definitions.
                              #     - hapi-swaggered: as extra OBJ to framework routers FUNC(). Also guess some from router definitions.
                              #     - koa-swagger-decorator: using imperative FUNC() calls|decorators
                              #     - koa-joi-router-docs: as extra OBJ to framework routers FUNC(). Also guess some from router definitions.
                              #     - loopback-swagger: from router definitions
                              #     - nestjs swagger: using imperative FUNC() calls|decorators
                              #     - sails-hook-swagger-generator: as extra OBJ to framework routers FUNC(). Also guess some from router definitions.
                              #From code comments (prefered):
                              #  - OpenAPI 2.0:
                              #     - swagger-jsdoc (prefered)
                              #From UI editor (prefered for non-developers):
                              #  - OpenAPI 2.0, 3.0:
                              #     - swagger-editor (prefered):
                              #        - by far the most high-profile
                              #        - views: YAML editor, swagger-ui documentation
                              #        - validation (official JSON schema, then several extra checks)
                              #        - most support for OpenAPI definition
                              #     - apicurio-studio (prefered if really need noob-friendly UI):
                              #        - views: YAML editor, noob-friendly UI
                              #     - openapi-gui:
                              #        - views: noob-friendly UI
                              #        - quite non-user-friendly and ugly
                              #  - OpenAPI 2.0:
                              #     - openapi-designer:
                              #        - not maintained
                              #        - views: noob-friendly UI, YAML editor, swagger-ui documentation

VERSION ==>                   #1.9.7
                              #Extract OpenAPI definition from JSDoc comments and JSON|YAML standalone files.
                              #Also validates and filters definitions using swagger-parser

                                  ┌──────────┐
                                  │   CORE   │
                                  └──────────┘

DEFINITIONS ==>               #Can be:
                              #  - JSDoc comment @swagger followed by YAML:
                              #     - consumes|produces 'MIME'_ARR
                              #     - tags TAG[_ARR]: ignore duplicates
                              #     - parameters|responses|securityDefinitions|definitions|paths.*: shallow merged to SPEC
                              #     - /PATH.*: shallow merged to SPEC.paths./PATH
                              #  - .y[a]ml file:
                              #     - same as JSDoc comment content but directly
                              #  - single .js|.json file (SPEC_FILE):
                              #     - base definition
                              #     - must contain top-level properties, at least SPEC.info.title|version
                              #     - required
SPEC_FILE.apis                #'GLOB'_ARR of files to parse for JSDoc comments and .y[a]ml files.

swagger-jsdoc                 #Extraction
-d SPEC_FILE
--definition SPEC-FILE        #
-o FILE
--output FILE                 #Output. Can be .json|y[a]ml. Def: ./swagger.json
-w
--watch                       #Using chokidar (see its doc)

SWAGGER-JSDOC(OPTS)->OBJ      #Same as Node module
                              #OPTS: swaggerDefinition SPEC_OBJ, apis 'GLOB'_ARR