Quick Start: Add a New Path

Quick Start: Add a New Path

1. First, open up the swagger editor by running: $ a127 project edit
2. Under the paths object, add the new path as follows:

        paths:
          /weather:
            x-swagger-router-controller: weather
            x-volos-authorizations: {}
            x-volos-apply: {}
            get:
              description: "Returns current weather to the caller"
              operationId: weather
              produces:
                - application/json
              parameters:
                - name: city
                  in: query
                  description: "The city you want weather for in the form city,country"
                  required: true
                  type: string
              responses:
                "200":
                  description: Success	

x-swagger-router-controller is a custom Apigee 127 extension to the Swagger model that maps a path to a controller file. For instance, /weather gets mapped to api/controller/weather.js.

x-volos-authorizations can be used to apply schemes such as OAuth2 and x-volos-apply can be used to apply volos quotas (Quickstart: Add Quotas) and caches (Quickstart: Add Caching).

The other keys conform to the Swagger 2.0 specifications. The parameters is a YAML array that defines all the parameters required for the call. The responses object defines the response specifications for response codes.

3. Now we can go ahead and implement the actual controller by creating a file called weather.js in the api/controllers folder.
4. The weather.js file should contain a function that will take in request and response objects, query the Open Weather Map API using the city query parameter and return the current weather conditions. Open Weather returns a JSON object. Finally, we also need to export this function so that it is available to the outside world.

        'use strict';

        var util = require('util');
        var http = require('http');
        module.exports = {
          weather: weather
        }

        function weather(req, res) {
          var city = req.swagger.params.city.value;
          http.request({
            hostname:  'api.openweathermap.org',
            path: '/data/2.5/weather/?q='+city+'&units=imperial',

          }, function(resp) {
            res.json(resp.main.temp);
          });     
        }

5. The swagger specification allows us to define both the request and the response model. We defined the request parameters for the weather path above. To specify the response model, we need to add the schema field to our responses.

        responses:
          "200":
            description: Success
            schema:
              $ref: "#/definitions/WeatherResponse"
          default:
            description: Error
            schema:
              $ref: "#/definitions/ErrorResponse"

In the schema we use the $ref type to refer to another YAML object defined under definitions:

        definitions:
          HelloWorldResponse:
            required:
              - message
            properties:
              message:
                type: string
          ErrorResponse:
            required:
              - message
            properties:
              message:
                type: string
          WeatherResponse:
            required:
              - temp
            properties:
              temp:
                type: float