Swagger-PHP for generating JSON file for Swagger-UI

I am trying to use Swagger-PHP for generating JSON files , so that I can use it with Swagger-UI for auto documentation.

I tried the link :- https://github.com/zircote/swagger-php

Also I tried to work around with there documentation at http://zircote.com/swagger-php/installation.html

But my hard luck , I am unable to implement it.

I am able to install composer correctly. Also the bundle of Swagger-PHP is installed correctly.

But the problem is that I am unable to use/understand the test examples provided by them.

So if anyone has worked it around please help !!

Thanks in advance !!

Solution

You just put comments aka annotations in your code, model example:

/**
* @SWG\Model(
* id="vps",
* required="['type', 'hostname']",
*  @SWG\Property(name="hostname", type="string"),
*  @SWG\Property(name="label", type="string"),
*  @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")
* )
*/
class HostVps extends Host implements ResourceInterface
{
    // ...
}

Controller example:

/**
 * @SWG\Resource(
 *  basePath="http://skyapi.dev",
 *  resourcePath="/vps",
 *  @SWG\Api(
 *   path="/vps",
 *   @SWG\Operation(
 *    method="GET",
 *    type="array",
 *    summary="Fetch vps lists",
 *    nickname="vps/index",
 *    @SWG\Parameter(
 *     name="expand",
 *     description="Models to expand",
 *     paramType="query",
 *     type="string",
 *     defaultValue="vps,os_template"
 *    )
 *   )
 *  )
 * )
 */
 class VpsController extends Controller
 {
     // ...
 }

Then in console:

php swagger.phar ./your-code-source/ -o ./directory-for-output-files

Then link generated files in Swagger UI. Is this help?

BTW, this documentation: http://zircote.com/swagger-php/annotations.html is incomplete. It's better to rely on parser errors, example:

php swagger.phar ./skynode-api/api/ -o ./foo
Swagger-PHP 0.9.0
-----------------
[INFO] Skipping unsupported property: "foo" for @Swagger\Annotations\Property, expecting "name", "description", "type", "format", "items", "uniqueItems", "required", "minimum", "maximum", "enum", "defaultValue", "_partialId", "_partials" in HostVps in /home/kane/some-dir/some-file.php on line 3

EDIT: Swagger 2.0 has pretty good specification on GitHub

BTW, consider to use Swagger Editor to create api specification file (json/yaml) to use in Swagger UI. Cause inline SWG documentation in php files is just ugly and you don't have autocomplete support in IDE.