Skip to content

Commit 20ae5aa

Browse files
weierophinneyweierophinney
committed
Merge branch 'feature/5'
Close #5
2 parents 0e3476b + 9eef043 commit 20ae5aa

File tree

1 file changed

+162
-12
lines changed

1 file changed

+162
-12
lines changed

‎README.md

Lines changed: 162 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,168 @@
1-
Apigility Documentation Models
2-
==============================
1+
ZF Apigility Documentation
2+
==========================
33

44
[![Build Status](https://travis-ci.org/zfcampus/zf-apigility-documentation.png)](https://travis-ci.org/zfcampus/zf-apigility-documentation)
5-
[![Coverage Status](https://coveralls.io/repos/zfcampus/zf-apigility-documentation/badge.png?branch=master)](https://coveralls.io/r/zfcampus/zf-apigility-documentation)
5+
6+
Introduction
7+
------------
68

79
This ZF2 module can be used with conjunction with Apigility in order to:
810

911
- provide an object model of all captured documentation information, including:
10-
- All APIs available
11-
- All Services available in each API
12-
- All Operations available in each API
13-
- All required/expected Accept and Content-Type request headers, and expected
14-
Content-Type response header, for each available API Service Operation.
15-
- All configured fields for each service
16-
- provide a configurable MVC endpoint for returning documentation
17-
- documentation will be delivered in a serialized JSON structure by default
18-
- end-users may configure alternate/additional formats via content-negotiation
12+
- All APIs available.
13+
- All _services_ available in each API.
14+
- All _operations_ available for each service.
15+
- All required/expected `Accept` and `Content-Type` request headers, and expected
16+
`Content-Type` response header, for each available operation.
17+
- All configured fields for each service.
18+
- provide a configurable MVC endpoint for returning documentation.
19+
- documentation will be delivered in both HTML or serialized JSON by default.
20+
- end-users may configure alternate/additional formats via content-negotiation.
21+
22+
This module accomplishes all the above use cases by providing an endpoint to connect to
23+
(`/apigility/documentation[/:api[-v:version][/:service]]`), using content-negotiation to provide
24+
both HTML and JSON representations.
25+
26+
Installation
27+
------------
28+
29+
Run the following `composer` command:
30+
31+
```console
32+
$ composer require "zfcampus/zf-apigility-documentation:~1.0-dev"
33+
```
34+
35+
Alternately, manually add the following to your `composer.json`, in the `require` section:
36+
37+
```javascript
38+
"require": {
39+
"zfcampus/zf-apigility-documentation": "~1.0-dev"
40+
}
41+
```
42+
43+
And then run `composer update` to ensure the module is installed.
44+
45+
Finally, add the module name to your project's `config/application.config.php` under the `modules`
46+
key:
47+
48+
```php
49+
return array(
50+
/* ... */
51+
'modules' => array(
52+
/* ... */
53+
'ZF\Apigility\Documentation',
54+
),
55+
/* ... */
56+
);
57+
```
58+
59+
Configuration
60+
=============
61+
62+
### User Configuration
63+
64+
This module does not utilize any user configuration.
65+
66+
### System Configuration
67+
68+
The following configuration is defined by the module to ensure operation within a Zend Framework 2
69+
MVC application.
70+
71+
```php
72+
'router' => array(
73+
'routes' => array(
74+
'zf-apigility' => array(
75+
'child_routes' => array(
76+
'documentation' => array(
77+
'type' => 'Zend\Mvc\Router\Http\Segment',
78+
'options' => array(
79+
'route' => '/documentation[/:api[-v:version][/:service]]',
80+
'constraints' => array(
81+
'api' => '[a-zA-Z][a-zA-Z0-9_]+',
82+
),
83+
'defaults' => array(
84+
'controller' => 'ZF\Apigility\Documentation\Controller',
85+
'action' => 'show',
86+
),
87+
),
88+
),
89+
),
90+
),
91+
),
92+
),
93+
'controllers' => array(
94+
'factories' => array(
95+
'ZF\Apigility\Documentation\Controller' => 'ZF\Apigility\Documentation\ControllerFactory',
96+
),
97+
),
98+
'zf-content-negotiation' => array(
99+
'controllers' => array(
100+
'ZF\Apigility\Documentation\Controller' => 'Documentation',
101+
),
102+
'accept_whitelist' => array(
103+
'ZF\Apigility\Documentation\Controller' => array(
104+
0 => 'application/vnd.swagger+json',
105+
1 => 'application/json',
106+
),
107+
),
108+
'selectors' => array(
109+
'Documentation' => array(
110+
'ZF\Apigility\Documentation\JsonModel' => array(
111+
'application/json',
112+
),
113+
'Zend\View\Model\ViewModel' => array(
114+
'text/html',
115+
'application/xhtml+xml',
116+
),
117+
),
118+
),
119+
),
120+
'view_helpers' => array(
121+
'invokables' => array(
122+
'agacceptheaders' => 'ZF\Apigility\Documentation\View\AgAcceptHeaders',
123+
'agcontenttypeheaders' => 'ZF\Apigility\Documentation\View\AgContentTypeHeaders',
124+
'agservicepath' => 'ZF\Apigility\Documentation\View\AgServicePath',
125+
'agstatuscodes' => 'ZF\Apigility\Documentation\View\AgStatusCodes',
126+
),
127+
),
128+
'view_manager' => array(
129+
'template_path_stack' => array(
130+
__DIR__ . '/../view',
131+
),
132+
),
133+
```
134+
135+
ZF2 Events
136+
==========
137+
138+
This module has no events or listeners.
139+
140+
ZF2 Services
141+
============
142+
143+
### View Helpers
144+
145+
The following list of view helpers assist in making API documentation models presentable in view
146+
scripts.
147+
148+
- `ZF\Apigility\Documentation\View\AgAcceptHeaders` (a.k.a `agAcceptHeaders`) for making a
149+
list of `Accept` headers, escaped for HTML.
150+
- `ZF\Apigility\Documentation\View\AgContentTypeHeaders` (a.k.a `agContentTypeHeaders`) for
151+
making a list of `Content-Type` headers, escaped for HTML.
152+
- `ZF\Apigility\Documentation\View\AgServicePath` (a.k.a `agServicePath`) for making an HTML
153+
view representation of the route configuration of a service path.
154+
- `ZF\Apigility\Documentation\View\AgStatusCodes` (a.k.a `agStatusCodes`) for making an
155+
escaped list of status codes and their messages.
156+
157+
### Factories
158+
159+
#### `ZF\Apigility\Documentation\ApiFactory`
160+
161+
The `ApiFactory` service is capable of producing an object-graph representation of the desired
162+
API documentation that is requested. This object-graph will be composed of the following types:
163+
164+
- `ZF\Apigility\Documentation\Api`: the root node of an API.
165+
- `ZF\Apigility\Documentation\Services`: an array of services in the API (a service can be one
166+
of a REST or RPC style service).
167+
- `ZF\Apigility\Documentation\Operations`: an array of operations in the service.
168+
- `ZF\Apigility\Documentation\Fields`: an array of fields for a service.

0 commit comments

Comments
 (0)