This ZF2 module can be used with conjunction with Apigility in order to:
- provide an object model of all captured documentation information, including:
- All APIs available.
- All services available in each API.
- All operations available for each service.
- All required/expected
Accept
andContent-Type
request headers, and expectedContent-Type
response header, for each available operation. - All configured fields for each service.
- provide a configurable MVC endpoint for returning documentation.
- documentation will be delivered in both HTML or serialized JSON by default.
- end-users may configure alternate/additional formats via content-negotiation.
This module accomplishes all the above use cases by providing an endpoint to connect to
(/apigility/documentation[/:api[-v:version][/:service]]
), using content-negotiation to provide
both HTML and JSON representations.
Run the following composer
command:
$ composer require "zfcampus/zf-apigility-documentation:~1.0-dev"
Alternately, manually add the following to your composer.json
, in the require
section:
"require": {
"zfcampus/zf-apigility-documentation": "~1.0-dev"
}
And then run composer update
to ensure the module is installed.
Finally, add the module name to your project's config/application.config.php
under the modules
key:
return array(
/* ... */
'modules' => array(
/* ... */
'ZF\Apigility\Documentation',
),
/* ... */
);
This module does not utilize any user configuration.
The following configuration is defined by the module to ensure operation within a Zend Framework 2 MVC application.
'router' => array(
'routes' => array(
'zf-apigility' => array(
'child_routes' => array(
'documentation' => array(
'type' => 'Zend\Mvc\Router\Http\Segment',
'options' => array(
'route' => '/documentation[/:api[-v:version][/:service]]',
'constraints' => array(
'api' => '[a-zA-Z][a-zA-Z0-9_]+',
),
'defaults' => array(
'controller' => 'ZF\Apigility\Documentation\Controller',
'action' => 'show',
),
),
),
),
),
),
),
'controllers' => array(
'factories' => array(
'ZF\Apigility\Documentation\Controller' => 'ZF\Apigility\Documentation\ControllerFactory',
),
),
'zf-content-negotiation' => array(
'controllers' => array(
'ZF\Apigility\Documentation\Controller' => 'Documentation',
),
'accept_whitelist' => array(
'ZF\Apigility\Documentation\Controller' => array(
0 => 'application/vnd.swagger+json',
1 => 'application/json',
),
),
'selectors' => array(
'Documentation' => array(
'ZF\Apigility\Documentation\JsonModel' => array(
'application/json',
),
'Zend\View\Model\ViewModel' => array(
'text/html',
'application/xhtml+xml',
),
),
),
),
'view_helpers' => array(
'invokables' => array(
'agacceptheaders' => 'ZF\Apigility\Documentation\View\AgAcceptHeaders',
'agcontenttypeheaders' => 'ZF\Apigility\Documentation\View\AgContentTypeHeaders',
'agservicepath' => 'ZF\Apigility\Documentation\View\AgServicePath',
'agstatuscodes' => 'ZF\Apigility\Documentation\View\AgStatusCodes',
),
),
'view_manager' => array(
'template_path_stack' => array(
__DIR__ . '/../view',
),
),
This module has no events or listeners.
The following list of view helpers assist in making API documentation models presentable in view scripts.
ZF\Apigility\Documentation\View\AgAcceptHeaders
(a.k.aagAcceptHeaders
) for making a list ofAccept
headers, escaped for HTML.ZF\Apigility\Documentation\View\AgContentTypeHeaders
(a.k.aagContentTypeHeaders
) for making a list ofContent-Type
headers, escaped for HTML.ZF\Apigility\Documentation\View\AgServicePath
(a.k.aagServicePath
) for making an HTML view representation of the route configuration of a service path.ZF\Apigility\Documentation\View\AgStatusCodes
(a.k.aagStatusCodes
) for making an escaped list of status codes and their messages.
The ApiFactory
service is capable of producing an object-graph representation of the desired
API documentation that is requested. This object-graph will be composed of the following types:
ZF\Apigility\Documentation\Api
: the root node of an API.ZF\Apigility\Documentation\Services
: an array of services in the API (a service can be one of a REST or RPC style service).ZF\Apigility\Documentation\Operations
: an array of operations in the service.ZF\Apigility\Documentation\Fields
: an array of fields for a service.