3

I have searched and found i have been lost all day now, and I feel I am going round in circles.

I have written, (with help of a few guides), a simple API for my Yii based application.

I have now come to document this API for other to use it. I read everywhere that Swagger seems to be the way to go to implement, API documentation. However I can seem to get anywhere on how to use this application

I have followed the instructions on Swagger PHP Now I am lost has anyone got any examples of what to do next.

I have tried doing some self annotations of my ApiController.php and this doesnt work. I have been trying using the swagger.phar command line, but I still get no where. I know you will need a lot more information but i dont know what bits of info you need so rather than pasting lots of useless information please ask and i will send anything you need.

To be honest all i would like is some simple API documentation but it just seems impossible.

Cheers

Liam
  • 536
  • 8
  • 23
  • 1
    Question: Why dont you start with Documentation like doing it in APIARY.IO and almost than start to implementation in PHP? Sounds like the right way for me. – lin Jul 02 '14 at 17:49
  • Checking this now, this does seem a little easier thanks Liam – Liam Jul 02 '14 at 18:06
  • Check the proxy tool, which allows you to tunnel your APIARY.IO project onto your Test/Dev/Stage/Live- Systems. Cheers. – lin Jul 02 '14 at 18:09

1 Answers1

2

I have implemented swagger-php in my project. Please follow the below suggested instructions :

1) Download swagger-php(github.com/zircote/swagger-php) and swagger-ui(github.com/wordnik/swagger-ui). Extract them to your workspace.

2) Create a folder called swagger-api and blank php file called index.php in you workspace and paste the following code.

<?php
  use Swagger\Annotations as SWG;


/**
 * @SWG\Resource(
 *     apiVersion="0.2",
 *     swaggerVersion="1.2",
 *     resourcePath="/api.php",
 *     basePath="http://localhost/swagger-api/"
 * )
 */


// Run this in url

// localhost/index.php?action=get_app_list


// This is the API,show the list in array


/**
     *
     * @SWG\Api(
     *   path="/api.php?action=get_app_list",
     *   description="Operations about get app list",
     *   produces="['application/json']",
     *   @SWG\Operations(
     *     @SWG\Operation(
     *       method="GET",
     *       summary="Find facet by ID",
     *       notes="Returns a facet based on ID",
     *       type="ListResult",
     *       nickname="getAllResults", 
     *       @SWG\ResponseMessages(
     *          @SWG\ResponseMessage(
     *            code=400,
     *            message="Invalid ID supplied"
     *          ),
     *          @SWG\ResponseMessage(
     *            code=404,
     *            message="facet not found"
     *          )
     *       )
     *     )
     *   )
     * )
     */

    function get_app_list()
    {
      //normally this info would be pulled from a database.
      //build JSON array
      $app_list = array(array("id" => 1, "name" => "Web Demo"), 
    array("id" => 2, "name" => "Audio Countdown"), 
    array("id" => 3, "name" => "The Tab Key"), array("id" => 4,
    "name" => "Music Sleep Timer")); 
      return $app_list;
    }



    $possible_url = array("get_app_list");

    $value = "An error has occurred";

    if (isset($_GET["action"]) && in_array($_GET["action"], $possible_url))
    {
      switch ($_GET["action"])
        {
          case "get_app_list":
        $value = get_app_list();
        break;     
          $value = "Missing argument";
        break;
        }
    }

    //return JSON array
    echo(json_encode($value));
    ?>

3) Create a folder named swagger-docs in workspace.

4) Open you terminal and go the location of swagger-php in you workspace(i.e cd workpace/swagger-php).

5) Execute the following in your terminal php swagger.phar /workspace/swagger-api -o /workspace/swagger-docs (This can be executed where we contain swagger.phar file).

6) You will see some files created on your swagger docs folder.

7) Open index.html in swagger-ui/dist/

8) Replace -: url: "http://petstore.swagger.wordnik.com/api/api-docs" to url: "http:localhost/swagger-docs"

9) Run localhost/swagger-ui/dist in your browser.

triju
  • 29
  • 3