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 and Content-Type request headers, and expected Content-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.a agAcceptHeaders) for making a list of Accept headers, escaped for HTML.
• ZF\Apigility\Documentation\View\AgContentTypeHeaders (a.k.a agContentTypeHeaders) for making a list of Content-Type headers, escaped for HTML.
• ZF\Apigility\Documentation\View\AgServicePath (a.k.a agServicePath) for making an HTML view representation of the route configuration of a service path.
• ZF\Apigility\Documentation\View\AgStatusCodes (a.k.a agStatusCodes) for making an escaped list of status codes and their messages.
• ZF\Apigility\Documentation\View\AgTransformDescription (a.k.a agTransformDescription) 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.