1 | ## Configuration
|
2 |
|
3 | ** NOTE: The following applies to swagger-node apps replying on swagger-node-runner 0.5.x and better. (ie. Any app using swagger-connect 0.1.0, swagger-express-wm 0.1.0, swagger-hapi 0.1.0, swagger-restify 0.1.0, or swagger-sails 0.1.0 - or higher versions of the same.) **
|
4 |
|
5 | Swagger-Node application configuration is driven by the file `default.yaml` (by default) in the application's config directory. Configuration is driven by the [config](https://github.com/lorenwest/node-config/wiki/Configuration-Files) module, so reference its documentation to understand how you may set up configuration per environment and perform configuration overrides. By default, the configuration file looks something like this:
|
6 |
|
7 | ```yaml
|
8 | # swagger configuration file
|
9 |
|
10 | # values in the swagger hash are system configuration for swagger-node
|
11 | swagger:
|
12 |
|
13 | fittingsDirs: [ api/fittings, node_modules ]
|
14 | defaultPipe: null
|
15 | swaggerControllerPipe: swagger_controllers # defines the standard processing pipe for controllers
|
16 |
|
17 | # values defined in the bagpipes key are the bagpipes pipes and fittings definitions
|
18 | # (see https://github.com/apigee-127/bagpipes)
|
19 | bagpipes:
|
20 |
|
21 | _router:
|
22 | name: swagger_router
|
23 | mockMode: false
|
24 | mockControllersDirs: [ api/mocks ]
|
25 | controllersDirs: [ api/controllers ]
|
26 |
|
27 | _swagger_validate:
|
28 | name: swagger_validator
|
29 | validateResponse: true
|
30 |
|
31 | # pipe for all swagger-node controllers
|
32 | swagger_controllers:
|
33 | - onError: json_error_handler
|
34 | - cors
|
35 | - swagger_security
|
36 | - _swagger_validate
|
37 | - express_compatibility
|
38 | - _router
|
39 |
|
40 | # pipe to serve swagger (endpoint is in swagger.yaml)
|
41 | swagger_raw:
|
42 | name: swagger_raw
|
43 |
|
44 | # any other values in this file are just loaded into the config for application access...
|
45 | ```
|
46 |
|
47 | Important things to note:
|
48 |
|
49 | * All configuration for the Swagger-Node system is under the `swagger` key
|
50 | * Overall system behavior is driven by configuring the [Bagpipes](https://github.com/apigee-127/bagpipes) library
|
51 | * You may include other values and sections as you wish, they will just be loaded into the config for your application
|
52 | to access.
|
53 |
|
54 | Let's walk through the configuration:
|
55 |
|
56 | ### fittingsDirs
|
57 |
|
58 | Defines the directories Bagpipes will search for fittings that are defined or used in the bagpipes section below. Fittings are extension plugins that can either be installed (eg. https://www.npmjs.com/package/volos-swagger-oauth and https://www.npmjs.com/package/volos-swagger-apply) or written into your application directly.
|
59 |
|
60 | ### defaultPipe
|
61 |
|
62 | If no pipe is explicitly declared for a path or operation, this pipe will be played when that endpoint is hit.
|
63 |
|
64 | ### swaggerControllerPipe
|
65 |
|
66 | This names the standard pipe that plays for the swagger-node controllers (declared in the swagger.yaml with the
|
67 | extension `x-swagger-router-controller`). We'll look at how that's defined in a second.
|
68 |
|
69 | ### bagpipes
|
70 |
|
71 | This block is the configuration passed to the [bagpipes](https://github.com/apigee-127/bagpipes) underlying the application. As you can see, it defines not only the flow, but also the configuration of the elements.
|
72 |
|
73 | #### _router
|
74 |
|
75 | This configures the standard swagger-node router (currently swagger-tools). It tells it how to find your controllers, your mock controllers, and whether to run in mock mode.
|
76 |
|
77 | #### _swagger_validate
|
78 |
|
79 | This configures the swagger validator (currently swagger-tools). You can turn response validation on and off here.
|
80 |
|
81 | #### swagger_controllers
|
82 |
|
83 | Because this is specified as your controller pipe (in the `swaggerControllerPipe` setting above), this pipe plays for all paths and operations where you'veare specified a controller extension (`x-swagger-router-controller`).
|
84 |
|
85 | The default pipe is as follows:
|
86 |
|
87 | 1. set an error handler that converts all errors to JSON
|
88 | 2. run the [cors](https://www.npmjs.com/package/cors) module
|
89 | 3. execute swagger security (currently swagger-tools)
|
90 | 4. run swagger validator (currently swagger-tools)
|
91 | 5. add a few commonly used Express functions (if not already present) to request (path, query, get) and response (json,
|
92 | get, set, status).
|
93 | 6. run the router (currently swagger-tools)
|
94 |
|
95 | As you can see, you have full control over the pipeline and may add or remove elements you need for your specific application and environment.
|
96 |
|
97 | #### swagger_raw
|
98 |
|
99 | This serves your swagger file - on the path that is defined in your `api/swagger/swagger.yaml` and tagged with the `x-swagger-pipe` extension. It looks like this:
|
100 |
|
101 | ```yaml
|
102 | /swagger:
|
103 | x-swagger-pipe: swagger_raw
|
104 | ```
|
105 |
|
106 | Note: This automatically filters out all sections that are swagger extensions (`x-*`) by using a predefined regular expression: `/^(?!x-.*)/`.
|
107 |
|
108 | Naturally, if you don't wish to serve your swagger on this path or at all, you may change or remove this.
|
109 |
|
110 | This also conveniently serves as an example of how to map a path in your Swagger to a pipe. You may, of course, define and use any pipes you wish using any of the Bagpipes operations or add your own in your fittings directory.
|