zfcampus / zf-apigility-documentation
Apigility API documentation module
Installs: 1 311 193
Dependents: 24
Suggesters: 0
Security: 0
Stars: 12
Watchers: 9
Forks: 42
Open Issues: 14
Requires
- php: ^5.6 || ^7.0
- michelf/php-markdown: ^1.5
- zendframework/zend-inputfilter: ^2.7.2
- zendframework/zend-modulemanager: ^2.7.2
- zendframework/zend-mvc: ^2.7.15 || ^3.0.4
- zendframework/zend-servicemanager: ^2.7.6 || ^3.1
- zendframework/zend-view: ^2.8.1
- zfcampus/zf-apigility-provider: ^1.2
- zfcampus/zf-configuration: ^1.2
- zfcampus/zf-content-negotiation: ^1.2.1
Requires (Dev)
- phpunit/phpunit: ^5.7.27 || ^6.5.8 || ^7.1.5
- zendframework/zend-coding-standard: ~1.0.0
- zendframework/zend-stdlib: ^2.7.7 || ^3.0.1
This package is auto-updated.
Last update: 2020-01-20 17:19:15 UTC
README
Repository abandoned 2019-12-31
This repository has moved to laminas-api-tools/api-tools-documentation.
Introduction
This Zend Framework 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.
Requirements
Please see the composer.json file.
Installation
Run the following composer
command:
$ composer require zfcampus/zf-apigility-documentation
Alternately, manually add the following to your composer.json
, in the require
section:
"require": { "zfcampus/zf-apigility-documentation": "^1.2-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 [ /* ... */ 'modules' => [ /* ... */ 'ZF\Apigility\Documentation', ], /* ... */ ];
zf-component-installer
If you use zf-component-installer, that plugin will install zf-apigility-documentation as a module for you.
Configuration
User Configuration
This module does not utilize any user configuration.
System Configuration
The following configuration is defined by the module to ensure operation within a Zend Framework 2 MVC application.
namespace ZF\Apigility\Documentation; use Zend\ServiceManager\Factory\InvokableFactory; use Zend\View\Model\ViewModel; return [ 'router' => [ 'routes' => [ 'zf-apigility' => [ 'child_routes' => [ 'documentation' => [ 'type' => 'segment', 'options' => [ 'route' => '/documentation[/:api[-v:version][/:service]]', 'constraints' => [ 'api' => '[a-zA-Z][a-zA-Z0-9_.]+', ], 'defaults' => [ 'controller' => Controller::class, 'action' => 'show', ], ], ], ], ], ], ], 'service_manager' => [ 'factories' => [ ApiFactory::class => Factory\ApiFactoryFactory::class, ], ], 'controllers' => [ 'factories' => [ Controller::class => ControllerFactory::class, ], ], 'zf-content-negotiation' => [ 'controllers' => [ Controller::class => 'Documentation', ], 'accept_whitelist' => [ Controller::class => [ 0 => 'application/vnd.swagger+json', 1 => 'application/json', ], ], 'selectors' => [ 'Documentation' => [ ViewModel::class => [ 'text/html', 'application/xhtml+xml', ], JsonModel::class => [ 'application/json', ], ], ], ], 'view_helpers' => [ 'aliases' => [ 'agacceptheaders' => View\AgAcceptHeaders::class, 'agAcceptHeaders' => View\AgAcceptHeaders::class, 'agcontenttypeheaders' => View\AgContentTypeHeaders::class, 'agContentTypeHeaders' => View\AgContentTypeHeaders::class, 'agservicepath' => View\AgServicePath::class, 'agServicePath' => View\AgServicePath::class, 'agstatuscodes' => View\AgStatusCodes::class, 'agStatusCodes' => View\AgStatusCodes::class, 'agtransformdescription' => View\AgTransformDescription::class, 'agTransformDescription' => View\AgTransformDescription::class, ], 'factories' => [ View\AgAcceptHeaders::class => InvokableFactory::class, View\AgContentTypeHeaders::class => InvokableFactory::class, View\AgServicePath::class => InvokableFactory::class, View\AgStatusCodes::class => InvokableFactory::class, View\AgTransformDescription::class => InvokableFactory::class, ], ], 'view_manager' => [ 'template_path_stack' => [ __DIR__ . '/../view', ], ], ];
ZF Events
This module has no events or listeners.
ZF Services
View Helpers
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.ZF\Apigility\Documentation\View\AgTransformDescription
(a.k.aagTransformDescription
) for transforming the written descriptions into Markdown.
Factories
ZF\Apigility\Documentation\ApiFactory
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.