Swagger API Documentation Tutorial For PHP ZF2 Application

This tuto­r­i­al cov­ers instal­la­tion & inte­gra­tion of swag­ger in zf2 app, and con­fig­ur­ing your REST con­troller, action, mod­el to work with swag­ger , at the end of this tuto­r­i­al you will be hav­ing a beau­ti­ful swag­ger doc­u­men­ta­tion with UI for your appli­ca­tion.

What is swag­ger?

Swag­ger is REST API doc­u­men­ta­tion gen­er­a­tion tool, if you are going to devel­op REST API Appli­ca­tion then you need this tool for doc­u­men­ta­tion, You just have to add some anno­ta­tions in your func­tions and then it will auto­mat­i­cal­ly gen­er­ate a beau­ti­ful and user-friend­ly doc­u­men­ta­tion for your appli­ca­tion.

How swag­ger is dif­fer­ent from php­doc, api­gen ?

Swag­ger is not like php­doc & api­gen, it is only for REST API Doc­u­men­ta­tion, at oth­er hand php­doc, api­gen pro­vides doc­u­men­ta­tion for all your class­es & func­tions & prop­er­ties, it is basi­cal­ly a devel­op­er doc­u­men­ta­tion, but Swag­ger is REST API doc­u­men­ta­tion. So both are total­ly dif­fer­ent.

 

Set­ting up Swag­ger with ZF2 PHP

Step 1. Go to your appli­ca­tion root fold­er and open composer.json (if not there then cre­ate) and add these two pack­ages -

and run the com­pos­er with update option — php composer.phar update

Step 2.  Thats it all done, 🙂 swag­ger is imple­ment­ed with your code now you have to add anno­ta­tions to your con­troller , mod­els, actions.

Swag­ger PHP Anno­ta­tions

(Note: in this tuto­r­i­al i will be cov­er­ing only few anno­ta­tions , you can read more about swag­ger php anno­ta­tions at Here )

Step 3. Open your rest con­troller (zf2 con­troller) and add the fol­low­ing anno­ta­tions just above the class

So now your con­troller will look like this

Step 4: Now add anno­ta­tion for action method-

As you can see i have men­tioned here type prop­er­ty to Project,  it means that this action will return Project Mod­el object.

So you need to have a Project Mod­el ( or any mod­el accord­ing to your appli­ca­tion, it can be doc­trine enti­ty too)

Step 5: So now open your mod­el class and add this anno­ta­tion there -

Note that if you are using doc­trine then you have to add doc­trine anno­ta­tions sep­a­rate such as -

adding both anno­ta­tions in one com­ment was not work­ing for me.

Step 6: Set­up the con­fig­u­ra­tion

You have to add swag­ger con­fig­u­ra­tion file to your zend frame­work 2 appli­ca­tion:

Open your application.config.php and add this mod­ule — ‘Swag­ger­Mod­ule’ to the list of mod­ule.

and run these com­mand from your zend frame­work 2 appli­ca­tion root

So now you have swagger.global.php inside your autoload con­fig fold­er.

Step 7: So thats it , now its time to gen­er­ate the json files

for that we will use the tool pro­vid­ed by swag­ger-

go to your appli­ca­tion root fold­er and run the fol­low­ing com­mand -

this file can take upto 20 sec­onds, now you can see the jsons file inside your public/ap

These json file con­tains all the meta infor­ma­tion about your appli­ca­tion which you have men­tion

Step 8: Swag­ger UI

Now lets cre­ate UI For your doc­u­men­ta­tion.

cre­ate a sym­link to swag­ger ui inside your pub­lic fold­er, for that nav­i­gate to zf2 appli­ca­tions ‘pub­lic’ fold­er and cre­ate this sym­link

Thats it now you can see your doc­u­men­ta­tion at local.yourdomain.com/api/swagger.

Feel free to com­ment if you are fac­ing any prob­lem.

vivek

Web Developer & Server Admin, Skilled in Java , PHP , LAMP, Tomcat, Mongo DB & SQL. Available for freelancing project or Open Source Contribution, Feel free to contact me at contact@viveksoni.net .

You may also like...

  • Muhammed Kha­lan­der

    Awe­some vivek, works like a charm

    • Thanks, Glad to help you.