1 |
|
2 | ## About controllers
|
3 |
|
4 | * [Implementing a controller](#implementing)
|
5 | * [Using query parameters](#query)
|
6 | * [Weather API example](#weather)
|
7 |
|
8 | ### <a name="implementing"></a>Implementing a controller
|
9 |
|
10 | This topic explains how to implement a controller. The `x-swagger-router-controller` Swagger extension element is used to specify the name of a controller file. The quick start example defines a `hello_world` controller file, which is by default in `api/controllers/hello_world.js`.
|
11 |
|
12 | ```yaml
|
13 | paths:
|
14 | /hello:
|
15 | # binds swagger app logic to a route
|
16 | x-swagger-router-controller: hello_world
|
17 | ```
|
18 |
|
19 | By default, controller method names map to the HTTP operation names, like get() or post(). But you can specify any name you wish with the `operationId` element. In the following example, a GET request results in calling the hello() method in the controller.
|
20 |
|
21 | ```yaml
|
22 | get:
|
23 | description: Returns 'Hello' to the caller
|
24 | # used as the method name of the controller
|
25 | operationId: hello
|
26 | ```
|
27 |
|
28 | Here is the `hello_world.js` implementation for the quick start example. It retrieves the query parameter value and returns a response.
|
29 |
|
30 | ```javascript
|
31 | var util = require('util');
|
32 |
|
33 | module.exports = {
|
34 | hello: hello
|
35 | };
|
36 |
|
37 | function hello(req, res) {
|
38 | var name = req.swagger.params.name.value;
|
39 | var hello = name ? util.format('Hello, %s', name) : 'Hello, stranger!';
|
40 | res.json(hello);
|
41 | }
|
42 | ```
|
43 |
|
44 | ### <a name="query"></a>Using query parameters
|
45 |
|
46 | In the controller code, we obtained the value of a query parameter and echoed it back in the response. We used the `req.swagger` object to obtain access to the query parameters. You declare query parameters in the paths section of the project's Swagger definition. For example:
|
47 |
|
48 | ```yaml
|
49 | parameters:
|
50 | - name: name
|
51 | in: query
|
52 | description: The name of the person to whom to say hello
|
53 | required: false
|
54 | type: string
|
55 | ```
|
56 |
|
57 | The req.swagger object is populated by the swagger-tools middleware component of swagger. To read more about this object, see the [Swagger tools middleware documentation](https://github.com/apigee-127/swagger-tools/blob/master/docs/Middleware.md).
|
58 |
|
59 | ### <a name="weather"></a>Weather API example
|
60 |
|
61 | Let's look at an example controller for a simple weather API.
|
62 |
|
63 | The Weather API requires a controller function that takes in request and response objects, queries the Open Weather Map API using the `city` query parameter and returns the current weather conditions.
|
64 |
|
65 | Note that Open Weather returns a JSON object. Also, we'll need to export the controller function so that it is available to the outside world.
|
66 |
|
67 | We will use the `request` library to make the request. So, add it to `package.json`:
|
68 |
|
69 | ```javascript
|
70 | "dependencies": {
|
71 | "request": ""
|
72 | },
|
73 | ```
|
74 |
|
75 | >Note: If a controller requires additional Node.js modules, be sure to add them to your package.json file and execute `npm install`.
|
76 |
|
77 | In the Swagger file, you can see that when a GET is performed on `/weather`, the target controller file is `api/controllers/weather.js`, and the target method to call is getWeatherByCity():
|
78 |
|
79 | ```yaml
|
80 | paths:
|
81 | /weather:
|
82 | x-swagger-router-controller: weather
|
83 | get:
|
84 | description: "Returns current weather in the specified city to the caller"
|
85 | operationId: getWeatherByCity
|
86 | parameters:
|
87 | - name: city
|
88 | in: query
|
89 | description: "The city you want weather for in the form city,state,country"
|
90 | required: true
|
91 | type: "string"
|
92 | ```
|
93 |
|
94 | Here is the controller implementation for the `getWeatherByCity` function:
|
95 |
|
96 | ```javascript
|
97 | 'use strict';
|
98 |
|
99 | var util = require('util');
|
100 | var request = require('request');
|
101 |
|
102 | module.exports = {
|
103 | getWeatherByCity: getWeatherByCity
|
104 | }
|
105 |
|
106 | function getWeatherByCity(req, res) {
|
107 | var city = req.swagger.params.city.value;
|
108 | var url = "http://api.openweathermap.org/data/2.5/weather?q="+city+"&units=imperial";
|
109 | console.log('Executing request: '+url);
|
110 | request.get(url).pipe(res);
|
111 | };
|
112 | ```
|
113 |
|
114 |
|
115 | Here is how you call the Weather API, which returns data for a specified city.
|
116 |
|
117 | ```bash
|
118 | curl http://localhost:10010/weather\?city\=San%20Jose,CA
|
119 | ```
|
120 |
|
121 |
|
\ | No newline at end of file |