Example: Mocking up API controller function "contacts.listContacts()" to handle Swagger defined route

[nfloersch]

The contacts route in the YAML is defined here:

/contacts/:
    x-swagger-router-controller: contacts
    get:
      summary: Get all contacts
      description: Returns a list of all registered contacts with filtering support
      operationId: listContacts

The YAML file defines the route (/contacts), controller (x-swagger-router-controller: contacts), and function name (operationId: listContacts) that will be called.

hsda-cfbtv/api/swagger/swagger.yaml

Line 28 in ce6e863

operationId: listContacts

For the contacts controller, we need to mock up a listContacts() function that takes in the parameters of the function as defined in the YAML, and responds with a JSON object that reflects those values back to the caller.

In the YAML the params are listed as:

      parameters:
        - in: query
          type: string
          name: query
          description: A query to filter list by (up to provider to determine what to search)
        - in: query
          type: string
          name: queries
          description: A comma separate list of queries with specific fields.
        - in: query
          type: number
          name: page
          default: 0
          description: The particular page of results.
        - in: query
          type: number
          name: per_page
          default: 25
          description: Number of records to return per page, up to 100.
        - in: query
          type: string
          name: sort_by
          default: name
          description: Which field to sort by.
        - in: query
          type: string
          name: order
          default: asc
          description: Which order to sort by (asc,desc).

This can be done as shown here:

// req and res are required inputs
function listContacts(req, res) {
  // variables defined in the Swagger document can be referenced using req.swagger.params.{parameter_name}
  var query = req.swagger.params.query.value || 'no query given';
  var queries = req.swagger.params.queries.value || 'no queries given';
  var page = req.swagger.params.page.value || 'no page given';
  var per_page = req.swagger.params.per_page.value || 'no per_page given';
  var sort_by = req.swagger.params.sort_by.value || 'no sort_by given';
  var order = req.swagger.params.order.value || 'no order given';
  var outputMessage = {
    'query': query,
    'queries': queries,
    'page': page,
    'per_page': per_page,
    'sort_by': sort_by,
    'order': order
  };

  // this sends back the JSON response
  res.json(outputMessage);
}