zfcampus / zf-apigility-documentation Goto Github PK

View Code? Open in Web Editor NEW

12.0 12.0 34.0 260 KB

License: BSD 3-Clause "New" or "Revised" License

PHP 89.21% HTML 10.79%

zf-apigility-documentation's People

Contributors

Stargazers

Watchers

zf-apigility-documentation's Issues

Error if allows_only_fields_in_filter exist

I am getting this kind of error if in zf-content-validation I added key allows_only_fields_in_filter

Code example

'zf-content-validation' => array(
        'Api\\V1\\Rest\\Test\\Controller' => array(
            'input_filter' => 'Api\\V1\\Rest\\Test\\Validator',
            'GET' => 'Api\\V1\\Rest\\Test\\Validator\\GET',
            'allows_only_fields_in_filter' => true
        ),
),

Please have a look on it and add fixes for this .

Thanks advanced.

Error details
/var/www/vendor/zfcampus/zf-apigility-documentation/src/ApiFactory.php at line : 207

E_NOTICE : Undefined offset: 1

Support to child routes

I'm using child routes with success in apigility, but the zfcampus/zf-apigility-documentation package apparently don't support the child routes.

Notice: Undefined index: my.route/is-child in ./vendor/zfcampus/zf-apigility-documentation/src/ApiFactory.php on line 190

Someone have any solution ?

Provide PHP 7.2 support

We need to update .travis.yml to test against PHP 7.2 (and any other previous versions if not listed). During this update we can also:

Remove HHVM support
Update PHPUnit to support 5.7, 6.0, and/or 7.0
Update to zend-coding-standard

Use of InputFilter type instead of real field type

Currently, the input filter type (i.e. Zend\InputFilter\FileInput for file upload) is set on the field 'type' entry. There is no way to define the type of the field (string, boolean, array, int...)

agAcceptHeaders called instead of agContentTypeHeaders

in file /view/zf-apigility-documentation/operation.phtml on line 122

Notices in configuration

If rpc module is not installed there is a notice:

( ! ) Notice: Undefined index: zf-rpc in ./vendor/zfcampus/zf-apigility-documentation/src/ApiFactory.php on line 67

Added possibility use collection query list

reuven770@023d81e

Accordingly need make changes in documentation-swagger
I updated to swagger 2.0 according Antevenio/zf-apigility-documentation-swagger@4cfbca0
and made in

zf-apigility-documentation-swagger/src/Service.php

    protected function getURLQueryParameters()
    {
        $queryWhitelist = $this->service->getQueryWhitelist();
        if (count($queryWhitelist) > 0) {
            $templateQueryParameters = [];
            foreach ($queryWhitelist as $paramSegmentName) {
                $templateQueryParameters[$paramSegmentName] = [
                'in' => 'query',
                'name' => $paramSegmentName,
                'description' => 'URL parameter ' . $paramSegmentName,
                'dataType' => 'string',
                'required' => false,
                'minimum' => 0,
                'maximum' => 1,
                'defaultValue' => ''
                ];
            }
            return $templateQueryParameters;
        } else return false;

    }

Also added support swagger summary

    protected function getPathOperation(Operation $operation, $parameters)
    {

        return $this->cleanEmptyValues([
                'tags' => [$this->service->getName()],
                'description' => $operation->getDescription(),
                'summary' => $operation->getSummary(),
                'parameters' => $parameters,
                'produces' => $this->service->getRequestAcceptTypes(),
                'responses' => $this->getResponsesFromOperation($operation)
        ]);
    }

Encoded backslash in route parameter

In Apigility documentation url contains module name. We added to generated module name own namespace. After this documentation has stopped working. We have found that problem is there https://github.com/zfcampus/zf-apigility-documentation/blob/master/config/module.config.php#L17 and we change regex to [a-zA-Z][a-zA-Z0-9_\\\\]+ what should cover namespace (MyNamespace\ApiName). However it doesn't work. One of working solution is [a-zA-Z][a-zA-Z0-9_%]+

First time reported in zendframework/zendframework#7409

Notices in zfcampus/zf-apigility-documentation/src/ZF/Apigility/Documentation/ApiFactory.php

I'm running into notices due to the documentation config not having values for request or response in some cases. Saving documentation for a delete on an entity for instance will not put any keys in the config for request or response which will cause a notice.

API documentation available on non-development mode api

On a deployment of Apigility API that is NOT in development mode, you can still access the documentation on the following url;

/apigility/documentation

Surely allowing the general public to get a sniff at the structure of your end points is bad?

Services not ordered in alphabetical order

Hi, currently services are not ordered alphabetically, it makes the documentation hard to use especially with lots of services.

So it could be great to sort the services before rendering.

Missing closing span tags

Lines 42 and 55 of view/zf-apigility-documentation/operation.phtml are missing closing span tags

Allow Markdown to generate standard HTML documentation

Hi, the admin Apigility GUI is great to manage REST documentation. I think it could be even better if we could write documentation in Markdown.

We could even have a preview mode in the administration GUI like the one we have in Github.

What do you think about this new feature ?

Allow new-lines in Method descriptions

The descriptions of Methods (ex. POST, GET, etc.) can have new-lines on data-entry, but the new-lines are ignored in this Documentaiton module.

As it stands right now, new-lines are, effectively, just spaces. This can make the description of a given method more more difficult to read when there is more than a few sentences.

See the screen-shot for an example of the desired effect: I have included the CSS ( white-space: pre ) on the related element.

Custom input filters for entities do not work in docs

Unless you have a matching collection verb and entity verb, a custom input filter's fields will not be used in the documentation. It seems to assume that the only verbs that need to be accounted for are the collection verbs. However, it's more likely that PUT and PATCH are for entities.

This means that POST, which is typically a collection verb, will use custom fields from a custom input validator. However, PATCH and PUT, being on entities, will not. If you enable PUT and PATCH at the collection level, then the docs will show the custom fields for the custom input validators for those verbs.

accept_whitelist and content_type_whitelist VS accept-whitelist and content-type-whitelist

in src/ApiFactory.php , because only accept_whitelist and content_type_whitelist are used, zf-content-negotiation data of non RPC services are not correctly assigned to $service->requestAcceptTypes and $service->requestContentTypes

Notice in documentation

array_map(): Argument #2 should be an array

in class

class AgAcceptHeaders extends AbstractHelper { /** * Render a list group of Accept headers composed by the service * * @param Service $service * @return string */ public function __invoke(Service $service) { $view = $this->getView(); $types = array_map(function ($type) use ($view) { return sprintf('<div class="list-group-item">%s</div>', $view->escapeHtml($type)); }, $service->getRequestAcceptTypes()); return implode("\n", $types); } }

The POST status code is wrong, 200 instead of 201

I moved here the issue zfcampus/zf-apigility-skeleton#62. The status code reported in the documentation for POST should be 201 "Created" and not 200.

Updating documentation on REST services does not work

When updating the documentation for a REST service I'm able to edit and save the global description, but unable to edit and save any of the individual GET / Collection / Entity documentation entries. It states that it has saved but does not update

Does not support nested elements

A nested resource is one which is described by nested objects such as:

{
  'id': 1,
  'email': 'email@email',
  'address': {
    'street': '....',
    'zipcode': '....'
  }
}

This example is trivial but it is not a stretch to come up with other more plausible scenarios.
Current implementation of the Field class and the ApiFactory class do not provide for such resource structure.

This limit extends to apigility-documentation-swagger which can be expected to display complex structures, as it is supported in other platforms.

The inputFilter class supports validation for a nested structure, so the capabilities do exist.

'input_filter_specs' => array(
       *'contact'* => array(
                *'type' => 'Zend\InputFilter\InputFilter',*
                'email' => array(
                    'name' => 'email',
                    'required' => false,
                    'validators' => array(
                        0 => array(
                            'name' => 'Zend\\Validator\\EmailAddress',
                            'options' => array(),
                        ),
                    ),

                    'description' => '',
                    'allow_empty' => false,
                    'continue_if_empty' => false,
                ),
            ),
    )
)

REST: Documentation for method-specific fields is not generated

When I try to add some fields for POST method, then they don't appear in documentation:

'zf-content-validation' => array(
    'AlbumService\\V1\\Rest\\Album\\Controller' => array(
        'POST' => 'AlbumService\\V1\\Rest\\Album\\NewAlbumValidator',
    ),
),
'input_filter_specs' => array(
    'AlbumService\\V1\\Rest\\Album\\NewAlbumValidator' => array(
        0 => array(
            'name' => 'name',
            'required' => true,
            'filters' => array(),
            'validators' => array(),
            'description' => 'Album name',
            'allow_empty' => false,
            'continue_if_empty' => false,
        ),
    ),
),

zf-apigility-documentation\src\ApiFactory.php seems to iterate only over the input_filter array, and it doesn't look POST, PUT and other custom validation elements:

    if (isset($this->config['zf-content-validation'][$serviceClassName]['input_filter'])) {
        $validatorName = $this->config['zf-content-validation'][$serviceClassName]['input_filter'];
        $fields = array();
        if (isset($this->config['input_filter_specs'][$validatorName])) {
            foreach ($this->config['input_filter_specs'][$validatorName] as $fieldData) {
                $fields[] = $field = new Field();
                $field->setName($fieldData['name']);
                if (isset($fieldData['description'])) {
                    $field->setDescription($fieldData['description']);
                }
                $field->setRequired($fieldData['required']);
            }
            $service->setFields($fields);
            $hasFields = true;
        }
    }

version 1.2.0 escapeTransformDescription not found

Last version (1.2.0) have this kind of error.
When I want just open the specific documentation, I got an error

URL:
apigility/documentation/myapi-v1

function usage is in file:

/vendor/zfcampus/zf-apigility-documentation/view/zf-apigility-documentation/operation.phtml
 line 41

 <td><?php echo $this->escapeTransformDescription($field->getDescription()) ?></td>

Can't find escapeTransformDescription() function

ERROR output

File:

/var/www/vendor/zendframework/zend-servicemanager/src/ServiceManager.php                    :555

Message:

Zend\View\HelperPluginManager::get was unable to fetch or create an instance for escapeTransformDescription

Stack trace:

#0 /var/www/vendor/zendframework/zend-servicemanager/src/AbstractPluginManager.php(161): Zend\ServiceManager\ServiceManager->get('escapeTransform...', true)
#1 /var/www/vendor/zendframework/zend-view/src/Renderer/PhpRenderer.php(373): Zend\ServiceManager\AbstractPluginManager->get('escapeTransform...', NULL)
#2 /var/www/vendor/zendframework/zend-view/src/Renderer/PhpRenderer.php(391): Zend\View\Renderer\PhpRenderer->plugin('escapeTransform...')
#3 /var/www/vendor/zfcampus/zf-apigility-documentation/view/zf-apigility-documentation/operation.phtml(41): Zend\View\Renderer\PhpRenderer->__call('escapeTransform...', Array)
#4 /var/www/vendor/zfcampus/zf-apigility-documentation/view/zf-apigility-documentation/operation.phtml(41): Zend\View\Renderer\PhpRenderer->escapeTransformDescription('')
#5 /var/www/vendor/zendframework/zend-view/src/Renderer/PhpRenderer.php(502): include('/var/www/vendor...')
#6 /var/www/vendor/zfcampus/zf-apigility-documentation/view/zf-apigility-documentation/service.phtml(25): Zend\View\Renderer\PhpRenderer->render('zf-apigility-do...', Array)
#7 /var/www/vendor/zendframework/zend-view/src/Renderer/PhpRenderer.php(502): include('/var/www/vendor...')
#8 /var/www/vendor/zfcampus/zf-apigility-documentation/view/zf-apigility-documentation/api.phtml(15): Zend\View\Renderer\PhpRenderer->render('zf-apigility-do...', Array)
#9 /var/www/vendor/zendframework/zend-view/src/Renderer/PhpRenderer.php(502): include('/var/www/vendor...')
#10 /var/www/vendor/zfcampus/zf-apigility-documentation/view/zf-apigility-documentation/show.phtml(6): Zend\View\Renderer\PhpRenderer->render('zf-apigility-do...', Array)
#11 /var/www/vendor/zendframework/zend-view/src/Renderer/PhpRenderer.php(502): include('/var/www/vendor...')
#12 /var/www/vendor/zendframework/zend-view/src/View.php(207): Zend\View\Renderer\PhpRenderer->render(Object(Zend\View\Model\ViewModel))
#13 /var/www/vendor/zendframework/zend-view/src/View.php(236): Zend\View\View->render(Object(Zend\View\Model\ViewModel))
#14 /var/www/vendor/zendframework/zend-view/src/View.php(200): Zend\View\View->renderChildren(Object(Zend\View\Model\ViewModel))
#15 /var/www/vendor/zendframework/zend-mvc/src/View/Http/DefaultRenderingStrategy.php(105): Zend\View\View->render(Object(Zend\View\Model\ViewModel))
#16 [internal function]: Zend\Mvc\View\Http\DefaultRenderingStrategy->render(Object(Zend\Mvc\MvcEvent))
#17 /var/www/vendor/zendframework/zend-eventmanager/src/EventManager.php(490): call_user_func(Array, Object(Zend\Mvc\MvcEvent))
#18 /var/www/vendor/zendframework/zend-eventmanager/src/EventManager.php(251): Zend\EventManager\EventManager->triggerListeners('render', Object(Zend\Mvc\MvcEvent))
#19 /var/www/vendor/zendframework/zend-mvc/src/Application.php(384): Zend\EventManager\EventManager->triggerEvent(Object(Zend\Mvc\MvcEvent))
#20 /var/www/vendor/zendframework/zend-mvc/src/Application.php(356): Zend\Mvc\Application->completeRequest(Object(Zend\Mvc\MvcEvent))
#21 /var/www/public/index.php(129): Zend\Mvc\Application->run()
#22 {main}