laminas-api-tools / api-tools-documentation
Laminas API Tools API documentation module
Fund package maintenance!
Community Bridge
Installs: 55 847
Dependents: 3
Suggesters: 0
Security: 0
Stars: 2
Watchers: 11
Forks: 9
Open Issues: 17
Requires
- php: ^5.6 || ^7.0
- laminas-api-tools/api-tools-configuration: ^1.2
- laminas-api-tools/api-tools-content-negotiation: ^1.2.1
- laminas-api-tools/api-tools-provider: ^1.2
- laminas/laminas-inputfilter: ^2.7.2
- laminas/laminas-modulemanager: ^2.7.2
- laminas/laminas-mvc: ^2.7.15 || ^3.0.4
- laminas/laminas-servicemanager: ^2.7.6 || ^3.1
- laminas/laminas-view: ^2.8.1
- laminas/laminas-zendframework-bridge: ^1.0
- michelf/php-markdown: ^1.5
Requires (Dev)
- laminas/laminas-coding-standard: ~1.0.0
- laminas/laminas-stdlib: ^2.7.7 || ^3.0.1
- phpunit/phpunit: ^5.7.27 || ^6.5.8 || ^7.1.5
Replaces
README
Introduction
This Laminas module can be used with conjunction with Laminas API Tools 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
(/api-tools/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 laminas-api-tools/api-tools-documentation
Alternately, manually add the following to your composer.json
, in the require
section:
"require": { "laminas-api-tools/api-tools-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' => [ /* ... */ 'Laminas\ApiTools\Documentation', ], /* ... */ ];
laminas-component-installer
If you use laminas-component-installer, that plugin will install api-tools-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 Laminas MVC application.
namespace Laminas\ApiTools\Documentation; use Laminas\ServiceManager\Factory\InvokableFactory; use Laminas\View\Model\ViewModel; return [ 'router' => [ 'routes' => [ 'api-tools' => [ '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, ], ], 'api-tools-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', ], ], ];
Laminas Events
This module has no events or listeners.
Laminas Services
View Helpers
The following list of view helpers assist in making API documentation models presentable in view scripts.
Laminas\ApiTools\Documentation\View\AgAcceptHeaders
(a.k.aagAcceptHeaders
) for making a list ofAccept
headers, escaped for HTML.Laminas\ApiTools\Documentation\View\AgContentTypeHeaders
(a.k.aagContentTypeHeaders
) for making a list ofContent-Type
headers, escaped for HTML.Laminas\ApiTools\Documentation\View\AgServicePath
(a.k.aagServicePath
) for making an HTML view representation of the route configuration of a service path.Laminas\ApiTools\Documentation\View\AgStatusCodes
(a.k.aagStatusCodes
) for making an escaped list of status codes and their messages.Laminas\ApiTools\Documentation\View\AgTransformDescription
(a.k.aagTransformDescription
) for transforming the written descriptions into Markdown.
Factories
Laminas\ApiTools\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:
Laminas\ApiTools\Documentation\Api
: the root node of an API.Laminas\ApiTools\Documentation\Services
: an array of services in the API (a service can be one of a REST or RPC style service).Laminas\ApiTools\Documentation\Operations
: an array of operations in the service.Laminas\ApiTools\Documentation\Fields
: an array of fields for a service.