What is Swagger:
Swagger is a annotations library for generating Swagger compatible JSON documentation for your API. The resulting JSON documentation may then be utilized for internal and external user friendly documentation, API portal sandbox with Swagger UI.
You might have an existing application exposing some API in your favorite PHP Framework.
Irrespective of your framework, Swagger can be integrated using Annotation.
Refer Swagger Annotations
PreRequisite:
a) PHP command should work in your console terminal or windows command line tool.
b) Use php -c FILE_PATH_OF_php.ini in case php command gives any error
Now its time to open terminal console and generate Swagger UI. Here are the steps to integrate:
- Download Swagger.phar
- Add swagger Annotation to PHP file
- Generate Swagger JSON files
- Install Swagger UI Project
- Open Swagger UI
1. Download Swagger.phar
Create a folder for Swagger generator. Name it as SwaggerGenerator.
Download composer.phar file from Composer Project.
Next run below line in console :
1 2 |
cd SwaggerGenerator php composer.phar require zircote/swagger-php |
After running above command, you should have swagger.phar in SwaggerGenerator/vendor/zircote/swagger-php/swagger.phar.
Copy that file and move it to SwaggerGenerator/swagger.phar
2. Add Swagger Annotation to PHP file
Sample PHP file with Swagger Annotation.
Add this Annotation as comments to your Controller or Class files as per your requirements.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
<?php /** * @SWG\Info( * title="PHP starter app cool API", * description="API for sign up & registration", * contact="php.api.support@codinglab.in" * ) * @SWG\Authorization( * type="oauth2", * @SWG\Scope(scope="token",description="Access token") * ) * @SWG\Resource( * apiVersion="v0", * swaggerVersion="2.0", * resourcePath="/api/oauth", * basePath="http://ci.com/api" * ) */ class Api { /** * * @SWG\Api( * path="/api/about", * description="Sample about API page", * @SWG\Operation(method="GET", summary="About PHP API", notes="Returns a sample output", * type="About", nickname="getSampleAbout", * @SWG\Parameter(name="userId", type="string"), * @SWG\ResponseMessage(code=404, message="Validation errors "), * @SWG\ResponseMessage(code=500, message="Internal error") * ) * ) */ function index_get(){ $this->set_response(["message" => "PHP API implementation"], REST_Controller::HTTP_ACCEPTED); } } |
3. Generate Swagger JSON files
Create a folder in your Apache DirectoryRoot called Swagger and a subfolder docs. Swagger/docs
1 2 |
cd SwaggerGenearator php swagger.phar "SOURCE_DIR_WithSwaggerAnnotation" -o DESTINATION_PATH_FOR_JSON |
1 |
Eg: php swagger.phar /var/www/MyProject/Application/ -o /var/www/Swagger/docs |
4. Install Swagger UI project
Download the swagger UI code from here and place it in Swagger/ui folder.
Edit ui/index.html and change the default URL in javascript so that it picks up your domain.
1 2 |
//url = "http://petstore.swagger.io/v2/swagger.json"; url = window.location.protocol + "//" + window.location.hostname + "/swagger/docs/"; |
5. Open Swagger UI
Go to browser and try to access “http://localhost/swagger/ui”. You will see below screens on the browser.