Quick Start: Add a New Path

Quick Start: Add a New Path

• First, open up the swagger editor by running: $ a127 project edit

• 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.

• Now we can go ahead and implement the actual controller by creating a file called weather.js in the api/controllers folder.

• 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. We will use the request library to make the request. So, add it to package.json

    "dependencies": {
      "request": ""
    },

  The weather function should look as follows:

  'use strict';

var util = require('util'); var request = require('request');

module.exports = { weather: weather }

function weather(req, res) { var city = req.swagger.params.city.value; var url = "http://api.openweathermap.org/data/2.5/weather?q="+city+"&units=imperial"; console.log('Executing request: '+url); request.get(url).pipe(res); };

* 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.

```yaml        
    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