Join the social network of Tech Nerds, increase skill rank, get work, manage projects...
 
  • How to Install Swagger in Cakephp 3.x ?

    • 0
    • 0
    • 0
    • 0
    • 0
    • 0
    • 1
    • 0
    • 834
    Comment on it

    Hello friends, today I am going to give basic understanding of installing Swagger in Cakephp 3. Before Installing it, let us understand what is Swagger.  Swagger is the most powerful framework which is designed to develop APIS and to create documentation. Just like postman, you can also test APIS by using Swagger. Lets start installing it.

     

    Installing Swagger in Cakephp 3.3

     

    Here we are going to use Cakephp 3 plugin which will going to add auto generated documentation in Swagger 2.0 using swagger-php and swagger-ui. Follow the steps below:

     

    Step 1: We need to install the plugin first using composer:

     

    composer require alt3/cakephp-swagger:dev-master

     

    This command will generate the following output:

     

    Loading composer repositories with package information
    Updating dependencies (including require-dev)
    Package operations: 5 installs, 0 updates, 0 removals
      - Installing symfony/finder (v3.2.1) Downloading: 100%         
      - Installing doctrine/lexer (v1.0.1) Downloading: 100%         
      - Installing doctrine/annotations (v1.2.7) Downloading: 100%         
      - Installing zircote/swagger-php (2.0.8) Downloading: 100%         
      - Installing alt3/cakephp-swagger (dev-master b4b21a6) Cloning b4b21a6f35
    Writing lock file
    Generating autoload files
    > Cake\Composer\Installer\PluginInstaller::postAutoloadDump

     

    Step 2: Now either run the following command in order to enable the plugin:

     

    bin/cake plugin load Alt3/Swagger --routes

    This command will generate the following:

    Welcome to CakePHP v3.3.11 Console
    ---------------------------------------------------------------
    App : src
    Path: /var/www/bikewale/src/
    PHP : 5.5.9-1ubuntu4.20
    ---------------------------------------------------------------
    
    /var/www/bikewale/config/bootstrap.php modified

     

    or you can also add the following line manually to your config/bootstrap.php file:

     

    Plugin::load('Alt3/Swagger', ['routes' => true]);

     

    Step 3: Now browse the following URL: http://localhost/bikewale/alt3/swagger . This page will now produce the Swagger-UI interface:

     

     

    Configuring Swagger

     

    Following file /config/swagger.php will be used to configure swagger plugin. Example is shown below:

     

    <?php
    use Cake\Core\Configure;
    
    return [
        'Swagger' => [
            'ui' => [
                'title' => 'ALT3 Swagger',
                'validator' => true,
                'api_selector' => true,
                'route' => '/swagger/',
                'schemes' => ['http', 'https']
            ],
            'docs' => [
                'crawl' => Configure::read('debug'),
                'route' => '/swagger/docs/',
                'cors' => [
                    'Access-Control-Allow-Origin' => '*',
                    'Access-Control-Allow-Methods' => 'GET, POST',
                    'Access-Control-Allow-Headers' => 'X-Requested-With'
                ]
            ],
            'library' => [
                'api' => [
                    'include' => ROOT . DS . 'src',
                    'exclude' => [
                        '/Editor/'
                    ]
                ],
                'editor' => [
                    'include' => [
                        ROOT . DS . 'src' . DS . 'Controller' . DS . 'AppController.php',
                        ROOT . DS . 'src' . DS . 'Controller' . DS . 'Editor',
                        ROOT . DS . 'src' . DS . 'Model'
                    ]
                ]
            ]
        ]
    ];

     

    User Interface

     

    Following Swagger-UI options can be used to customize the user interface of swagger:

     

    i) title: This will set the title of the browser to cakephp-swagger which is default.

    ii) validator: You can hide or show the validator image. Default value is true.

    iii) route: default routing is set to /alt3/swagger/. You can change it.

    iv) schemes: This is used to generate base url. Default is null

     

     

    'library' => [
        'api' => [
            'include' => ROOT . DS . 'src',
            'exclude' => [
                '/Editor/'
            ]
        ],
        'editor' => [
            'include' => [
                ROOT . DS . 'src' . DS . 'Controller' . DS . 'AppController.php',
                ROOT . DS . 'src' . DS . 'Controller' . DS . 'Editor',
                ROOT . DS . 'src' . DS . 'Model'
            ]
        ]
    ]

     

    You can browse the following url: http://localhost/bikewale/alt3/swagger/docs which will produce a json list with links . Example is shown below:

     

    {
        "success": true,
        "data": [
            {
                "document": "api",
                "link": "http://your.app/alt3/swagger/docs/api"
            },
            {
                "document": "editor",
                "link": "http://your.app/alt3/swagger/docs/editor"
            }
        ]
    }

     

    Copy and paste the following code to controller in cakephp

     

    <?php
    /**
        @SWG\Swagger(
            @SWG\Info(
                title="cakephp-swagger",
                description="Quickstart annotation example",
                termsOfService="http://swagger.io/terms/",
                version="1.0.0"
            )
        )
    
        @SWG\Get(
            path="/cakephp3/api/v1.0/users",
            summary="Retrieve a list of users",
            tags={"user"},
            consumes={"application/json"},
            produces={"application/xml", "application/json"},
            @SWG\Parameter(
                name="sort",
                description="Sort results by field",
                in="query",
                required=false,
                type="string",
                enum={"name", "description"}
            ),
            @SWG\Response(
                response="200",
                description="Successful operation",
                @SWG\Schema(
                    type="array",
                    ref="#/definitions/User"
                )
            ),
            @SWG\Response(
                response=429,
                description="Rate Limit Exceeded"
            )
        )
    
        @SWG\Definition(
            definition="User",
            required={"name", "description"},
            @SWG\Property(
                property="id",
                type="integer",
                description="CakePHP record id"
            ),
            @SWG\Property(
                property="name",
                type="string",
                description="CakePHP name field"
            ),
            @SWG\Property(
                property="description",
                type="string",
                description="Description of a most tasty cocktail"
            )
        )
    */
    
    
    /**
        @SWG\Post(
            path="/cakephp3/api/v1.0/createusers",
            summary="Add user",
            tags={"user"},
            consumes={"application/json"},
            produces={"application/json"},
            @SWG\Parameter(
                name="first_name",
                description="User's first name",
                in="formData",
                required=true,
                type="string"
            ),
            @SWG\Parameter(
               name="last_name",
               in="formData",
               description="User's last name",
               required=true,
               type="string"
              ),
            @SWG\Parameter(
               name="email",
               in="formData",
               description="User's email",
               required=true,
               type="string",
               format="email"
              ),
            @SWG\Parameter(
               name="password",
               in="formData",
               description="User's password",
               required=true,
               type="string",
               format="password"
              ),  
              @SWG\Parameter(
                name="role",
                description="User's role",
                in="formData",
                required=true,
                type="string",
                enum={"client", "consultant", "admin"}
            ),
              @SWG\Parameter(
                name="profile_pic",
                description="User's pic",
                in="formData",
                required=false,
                type="file"
            ),
            @SWG\Parameter(
               name="duration",
               in="formData",
               description="User's duration",
               required=true,
               type="integer"
            ),
            @SWG\Response(
                response="200",
                description="Successful operation",
                @SWG\Schema(
                    type="array",
                    ref="#/definitions/User"
                )
            ),
            @SWG\Response(
                response=429,
                description="Rate Limit Exceeded"
            )
        )
    
        @SWG\Definition(
            definition="Create User",
            required={"name", "description"},
            @SWG\Property(
                property="id",
                type="integer",
                description="CakePHP record id"
            ),
            @SWG\Property(
                property="name",
                type="string",
                description="CakePHP name field"
            ),
            @SWG\Property(
                property="description",
                type="string",
                description="Description of a most tasty cocktail"
            )
        )
    */

     

     

    This would result in following:

     

     

     

    Hope this blog will help to install swagger in cakephp 3.x .

    Thanks for reading the blog.

     

    How to Install Swagger in Cakephp 3.x ?

 0 Comment(s)

Sign In
                           OR                           
                           OR                           
Register

Sign up using

                           OR                           
Forgot Password
Fill out the form below and instructions to reset your password will be emailed to you:
Reset Password
Fill out the form below and reset your password: