Module Web API - mymagic/open_hub GitHub Wiki

WAPI (Web API) is a default module shipped with OpenHub. WAPI helps you easily setup and test your module API functions thru Swagger interface.

Assume our module here is demo Wapi support modularization architecture and able to read your module's swagger definition. protected/modules/wapi/controllers/V1Controller.php has been modified to auto load protected/modules/demo/actions/wapi/V1Controller/*.php for api action

Step 1: Define API YAML

Create a yaml file to catalog your module APIs at protected/modules/demo/data/api/demo.yaml.

An example of YAML looks like the following:

swagger: '2.0'
info:
  description: Demo module related API.
  version: "v1"
  title: Demo
  # put the contact info for your development or API team
  contact:
    email: [email protected]

  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

# tags are used for organizing operations
tags:
- name: public
  description: Public API calls available to any developers
- name: admin
  description: Secured admin only API calls
- name: internal
  description: Internal API calls available to in-house developers only
paths:
  /sayHello:
    post:
      tags:
      - public
      summary: Output friendly hello message
      description: An example to output hello message with the input name
      consumes:
      - application/x-www-form-urlencoded
      parameters:
      - in: formData
        name: guestName
        type: integer
        description: Name of the guest we like to say hello to
        required: true
        x-example: World
      produces:
      - application/json
      responses:
        200:
          description: OK
basePath: /v1
# Added by API Auto Mocking Plugin
host: api-central.mymagic.my
# Added by API Auto Mocking Plugin
schemes:
 - https

Step 2: Create WAPI Actions

Your API action sit at protected/modules/demo/actions/wapi/V1Controller/sayDemoHello.php

class sayDemoHello extends Action
{
	public function run()
	{
		$meta = array();
		$guestName = Yii::app()->request->getPost('guestName');
                $meta['input']['guestName'] = $guestName;
		
                try {
			$data = sprintf('Hello %s', $guestName);

			$this->getController()->outputSuccess($data, $meta);
		} catch (Exception $e) {
			$this->getController()->outputFail($e->getMessage(), $meta);
		}
	}
}

Outputting JSON

OpenHub ouput JSON in SoJF (Standard OpenHub JSON Format).

{
  "status": "success",
  "meta": {
    "input": {
      "var1FromPost": "abc",
      "var2FromPost": "def",
    },
    "output": {
      "total": 2
    }
  },
  "msg": "Everything works fine",
  "data": [
    {
      "orderId": "99",
      "productTitle": "4K LED TV",
      "deliveryLocation": "Cyberjaya, Malaysia",
      "buyerName": "Allen Tan"
    },
    {
      "orderId": "88",
      "productTitle": "Playstation 4",
      "deliveryLocation": "KLIA, Malaysia",
      "buyerName": "Foo Bar"
    }
  ]
}

V1Controller come with few helpful functions to output in SoJF:

public function outputMessage($msg, $meta = array())
{
    $this->outputJson('', $msg, 'success', $meta);
}

public function outputSuccess($data, $meta = array(), $msg = '')
{
    $this->outputJson($data, $msg, 'success', $meta);
}

public function outputFail($msg, $meta = array())
{
    $this->outputJson($data, $msg, 'fail', $meta);
}

public function outputPipe($result)
{
    $this->outputJson($result['data'], $result['msg'], ($result['status'] == 'success' || $result['success'] == true) ? true : false, $result['meta']);
}