zfcampus / zf-apigility-documentation-swagger
Apigility API Swagger documentation module
Installs: 569 548
Dependents: 4
Suggesters: 0
Security: 0
Stars: 12
Watchers: 8
Forks: 35
Open Issues: 12
Language:JavaScript
Requires
- php: ^5.6 || ^7.0
- zendframework/zend-eventmanager: ^2.6.3 || ^3.0.1
- 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-api-problem: ^1.2.1
- zfcampus/zf-apigility-documentation: ^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-http: ^2.5.4
- zendframework/zend-stdlib: ^2.7.7 || ^3.0.1
This package is auto-updated.
Last update: 2020-01-20 17:22:45 UTC
README
Repository abandoned 2019-12-31
This repository has moved to laminas-api-tools/api-tools-documentation-swagger.
Introduction
This module provides Apigility the ability to show API documentation through a Swagger UI.
The Swagger UI is immediately accessible after enabling this module at the URI path /apigility/swagger
.
In addition to providing the HTML UI, this module also plugs into the main Apigility documentation
resource (at the path /apigility/documentation
) in order to allow returning a documentation
payload in the application/vnd.swagger+json
media type; this resource is what feeds the Swagger
UI. You can access this representation by passing the media type application/vnd.swagger+json
for
the Accept
header via the path /apigility/documentation/:module/:service
.
Requirements
Please see the composer.json file.
Installation
Run the following composer
command:
$ composer require zfcampus/zf-apigility-documentation-swagger
Alternately, manually add the following to your composer.json
, in the require
section:
"require": { "zfcampus/zf-apigility-documentation-swagger": "^1.2" }
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\Swagger', ], /* ... */ ];
zf-component-installer
If you use zf-component-installer, that plugin will install zf-apigility-documentation-swagger as a module for you.
Routes
/apigility/swagger
Shows the Swagger UI JavaScript application.
Assets: /zf-apigility-documentation-swagger/
Various CSS, images, and JavaScript libraries required to deliver the Swagger UI client application.
Configuration
System Configuration
The following is required to ensure the module works within a ZF2 and/or Apigility-enabled application:
namespace ZF\Apigility\Documentation\Swagger; return [ 'router' => [ 'routes' => [ 'zf-apigility' => [ 'child_routes' => [ 'swagger' => [ 'type' => 'segment', 'options' => [ 'route' => '/swagger', 'defaults' => [ 'controller' => SwaggerUi::class, 'action' => 'list', ], ], 'may_terminate' => true, 'child_routes' => [ 'api' => [ 'type' => 'segment', 'options' => [ 'route' => '/:api', 'defaults' => [ 'action' => 'show', ], ], 'may_terminate' => true, ], ], ], ], ], ], ], 'service_manager' => [ 'factories' => [ SwaggerViewStrategy::class => SwaggerViewStrategyFactory::class, ], ], 'controllers' => [ 'factories' => [ SwaggerUi::class => SwaggerUiControllerFactory::class, ], ], 'view_manager' => [ 'template_path_stack' => [ 'zf-apigility-documentation-swagger' => __DIR__ . '/../view', ], ], 'asset_manager' => [ 'resolver_configs' => [ 'paths' => [ __DIR__ . '/../asset', ], ], ], 'zf-content-negotiation' => [ 'accept_whitelist' => [ 'ZF\Apigility\Documentation\Controller' => [ 0 => 'application/vnd.swagger+json', ], ], 'selectors' => [ 'Documentation' => [ ViewModel::class => [ 'application/vnd.swagger+json', ], ], ], ], ];
ZF Events
Listeners
ZF\Apigility\Documentation\Swagger\Module
This listener is attached to the MvcEvent::EVENT_RENDER
event at priority 100
. Its purpose is
to conditionally attach a view strategy to the view system in cases where the controller response is
a ZF\Apigility\Documentation\Swagger\ViewModel
view model (likely selected as the
content-negotiated view model based off of Accept
media types).
ZF Services
View Models
ZF\Apigility\Documentation\Swagger\ViewModel
This view model is responsible for translating the available ZF\Apigility\Documentation
models
into Swagger-specific models, and further casting them to arrays for later rendering as JSON.