One of the cool feature of Apigility is the ability to generate API documentation using a simple UI. The documentation is generated in HTML format, and optionally in Swagger format. The API documentation is reported in Apigility in the top bar, under the menu "API Docs".
In order to generate the API documentation you need to insert some desciptions before. All the information to edit are reported in the Documentation tab on each REST or RPC service.
For each service and for each HTTP method, you can specify a description of the action. In case of RESTful services you can also specify different information for an Entity and a Collection. An interesting feature of the API documentation is the ability to generate the Response Body specification from the configuration, using the "generate from configuration" button.
This button read the configuration of the API and propose a JSON response based on the fields specified (the fields are documented under the Fields tab of each REST and RPC service). Of course, you can edit the response body changing the output, if you need.
Once you have added some API descriptions, you can go to the "API Docs" menu and show the API documentation (in our case version 1).
You will see all the API documentation in HTML format, using the Bootstrap 3 template. You can expand and collapse the information on each HTTP method clicking on the name. All the API documentation are exposed in the /apigility/documentation base URL.
How to install the Swagger adapter
To activate the Swagger adapter for the API documentation, you need to add the following dependency in the composer.json file (in the require field):
"zfcampus/zf-apigility-documentation-swagger": "~1.0-dev"
and execute the composer update commmand.
After the installation of zf-apigility-documentation-swagger you need to enable this module in the config/application.config.php file. You have to edit this configuration file and add the following line after the 'ZF\Apigility\Documentation':
'ZF\Apigility\Documentation\Swagger',
Now you can go to the Swagger documentation from the welcome screen, clicking on the Swagger API documentation button, or going directly to the /apigility/swagger URL. To show the Swagger UI render you have to select the API service version and you will see a web page like the one reported in Figure 5 (using Swagger UI).
Customizing the API documentation module
The API documentation feature is offered by Apigility using the zf-apigility-documentation module, written in Zend Framework 2. This module provide an object model of all captured documentation information, including:
- All APIs available
- All Services available in each API
- All Operations available in each API
- All required/expected Accept and Content-Type request headers, and expected Content-Type response header, for each available API Service Operation.
- All configured fields for each service
Moreover, it provides a configurable MVC endpoint for returning documentation:
- documentation will be delivered in a serialized JSON structure by default
- end-users may configure alternate/additional formats via content-negotiation
If you want to customize the format of your API documentation you can have a look at the source code of the zf-apigility-documentation-swagger module. Basically, you need to create a custom route for your format (see the Swagger module.config.php) and use the ZF\Apigility\Documentation\ApiFactory to access the data for the API documentation services. The view model to implement needs to manage a list view and a show view, that's it.
All the API documentation formats are driven by content negotiation (using the zf-content-negotiation module). For instance, to get the API documentation data in Swagger format you can use the content negotiation "application/vnd.swagger+json".
For example, if you want to retrieve the API documentation data in JSON format you can use the following request (using HTTPie):
http GET http://localhost:8888/apigility/documentation[/api]/[service] 'Accept:application/json'
where [api] is the name of the API and [service] is the name of the REST or RPC service. To get the same result in Swagger format you can use the following request:
http GET http://localhost:8888/apigility/documentation/[api]/[service] 'Accept:application/vnd.swagger+json'