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

3
  • 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. Commented Jul 2, 2014 at 17:49
  • Checking this now, this does seem a little easier thanks Liam Commented Jul 2, 2014 at 18:06
  • Check the proxy tool, which allows you to tunnel your APIARY.IO project onto your Test/Dev/Stage/Live- Systems. Cheers. Commented Jul 2, 2014 at 18:09

1 Answer 1

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.

Sign up to request clarification or add additional context in comments.

1 Comment

can u please explain more because m not getting exact idea

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.