Auto-generate your documentation for a PHP7 API

Loïc Boucha
Jan 3 · 4 min read
Credit: Dean Hochman — paperbacks

Here is an advice about all APIs you develop : you should write a good and strong documentation for it. The documentation should be clear and easily testable and you should start to write it from day one. After that, it’s probably too late already.

When an issue occurs with your api, if an external developer can easily understand and test it, it become easy to see if the problem is in your code or in his. Trust me, I’ve seen a lot of poor (or none) documented APIs and it can be a nightmare to start negotiating to decide which side is doing the job wrong.

Ok, so wee need a strong documentation. But let’s admit it : It’s an annoying and unpleasing job when you proudly wrote and tested all your code and you have to review it from zero to write all the doc.

Fortunately, there are tools allowing you to automate this process. Well, it does not going to write the doc for you, but if you can prepare everything you need while coding, you will spare you a lot of time and energy.

In this article, I’m going to show you how to self-generate API documentation for your PHP project. Let’s start.


1. Install PHP dependencies

You can proceed with your existing project or start a new one, you just need to work with composer and PHP7.

Install the package zircote/swagger-php

composer require zircote/swagger-php

Note: if you don’t work with the last version of PHP, which is my case, don’t forget to specify it to composer to avoid compatibility issues.

"config": {
"platform": {
"php": "7.0.0"
}
}

2. Create the openapi yaml file

Our self-generated documentation is an openapi file.

If you want more details about openapi, please visit: https://www.openapis.org/

That file will be parsed and rendered in HTML later. First, we need to create it. In this case, it will be a simple PHP file at the root public directory of my project.

Here is the php code to insert:

<?php
require
("../vendor/autoload.php");
$openapi = \OpenApi\scan(__DIR__.'/../src/Core/Controllers');
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

Of course, adapt the path of the vendor autoload and the path to scan. (In my case, all the REST functions will stand in src/Core/Controllers)

After doing that, here if what I get when I visit the url /doc.php:

It’s a little empty, but it you see the same thing, it works ! Let’s add a little documentation.

I my case, I want to document my login function:

public function postLogin() {
// ....
}

So, it’s a POST to /user/login. The API consume a json containing email and password. It’s quite simple.

Here is the doc comment to add in this case.

/**
*
@OA\Post(
* path="/user/login",
* tags={"users"},
* summary="Login",
* operationId="userLogin",
*
@OA\RequestBody(
* required=true,
*
@OA\MediaType(
* mediaType="application/json",
*
@OA\Schema(
*
@OA\Property(
* property="email",
* type="string",
* ),
*
@OA\Property(
* property="password",
* type="string",
* ),
* example={"email": "test@me.com", "password": "1234"}
* )
* )
* ),
*
@OA\Response(response="200", description="Login")
* )
*/
public function postLogin() {
// ....
}

Let’s see our doc file:

Well, it’s a bit better than the previous one ! Now we need to render it.

3. Render the openapi file

To render our openapi file to a user friendly documentation, we are going to use Swagger UI. Download it here: https://github.com/swagger-api/swagger-ui/archive/master.zip

Once downloaded, extract the zip and move the “dist” directory to your public directory. I renamed mine “doc”

After that, edit the index.html file and adapt url parameter in the JS at the end of file to fit with your openapi file:

const ui = SwaggerUIBundle({
url: "/doc.php",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})

This is what I see when visiting the “doc” url:

Conclusion

Now, you can generate your API doc on the fly for your PHP project !

Of course there are a lot of possibilities: the swagger-php by Zircote is full of examples to use to fit with your needs: https://github.com/zircote/swagger-php/tree/master/Examples

I hope this article will help you, and don’t hesitate to comment if it is incomplete or unclear at some point: It’s my first one on medium and english is not my native language.

I you liked this article and feel it useful, I’ll try to make others.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade