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: getWeatherByCity
          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.

• The Swagger specification allows us to define both the request and the response model. We defined the request parameters for the weather path above.
  The Open Weather API returns an object that looks like the following:

{
    "coord": {
        "lon": -77.58,
        "lat": 35.27
    },
    "sys": {
        "type": 1,
        "id": 1786,
        "message": 0.1057,
        "country": "United States of America",
        "sunrise": 1409913972,
        "sunset": 1409959883
    },
    "weather": [
        {
            "id": 500,
            "main": "Rain",
            "description": "light rain",
            "icon": "10n"
        },
        {
            "id": 211,
            "main": "Thunderstorm",
            "description": "thunderstorm",
            "icon": "11n"
        }
    ],
    "base": "cmc stations",
    "main": {
        "temp": 78.58,
        "pressure": 1021,
        "humidity": 88,
        "temp_min": 73.4,
        "temp_max": 82.4
    },
    "wind": {
        "speed": 5.62,
        "deg": 40
    },
    "clouds": {
        "all": 90
    },
    "dt": 1409876198,
    "id": 4474436,
    "name": "Kinston",
    "cod": 200
}

The cleanest way to define a model (schema) is to add it in the #/definitions section of the document and use $ref to refer to it from our path/operation. Below, we are specifying the model for a 200 response, referring to the WeatherResponse model and then the default model for all other responses referring to the ErrorResponse model:

    paths:
      /weather:
        ...      
        responses:
          "200":
            description: Success
            schema:
              $ref: WeatherResponse
          default:
            description: Error
            schema:
              $ref: ErrorResponse

Then in the #/definitions section of the Swagger document we would define the WeatherResponse model:

definitions:
  WeatherResponse:
  type: "object"
  properties: 
    base: 
      type: "string"
    clouds: 
      type: "object"
      properties: 
        all: 
          type: "number"
    cod: 
      type: "number"
    coord: 
      type: "object"
      properties: 
        lat: 
          type: "number"
        lon: 
          type: "number"
    dt: 
      type: "number"
    id: 
      type: "number"
    main: 
      type: "object"
      properties: 
        humidity: 
          type: "number"
        pressure: 
          type: "number"
        temp_max: 
          type: "number"
        temp_min: 
          type: "number"
        temp: 
          type: "number"
    name: 
      type: "string"
    sys: 
      type: "object"
      properties: 
        country: 
          type: "string"
        id: 
          type: "number"
        message: 
          type: "number"
        sunrise: 
          type: "number"
        sunset: 
          type: "number"
        type: 
          type: "number"
    weather: 
      type: "array"
      items: 
        type: "object"
        properties: 
          description: 
            type: "string"
          icon: 
            type: "string"
          id: 
            type: "number"
          main: 
            type: "string"
    wind: 
      type: "object"
      properties: 
        deg: 
          type: "number"
        speed: 
          type: "number"