zfcampus / zf-apigility-documentation Goto Github PK
View Code? Open in Web Editor NEWLicense: BSD 3-Clause "New" or "Revised" License
License: BSD 3-Clause "New" or "Revised" License
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)
]);
}
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;
}
}
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 ?
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.
Hi I've found a typo on line 10 in module.config.php
use Zend\View\Modle\ViewModel;
should be Zend\View\Model\ViewModel;
I use the use_raw_data parameter.
It works fine in 1.1.0 but not in 1.1.1
I got a notice: Undefined offset: 1 in /var/www/api/vendor/zfcampus/zf-apigility-documentation/src/ApiFactory.php on line 202
This commit f5c1648#diff-c89e23dbc0bb01f8f7f6bc7c2c066a79 change the behaviour.
Each parameter is now consider as a pair of validatorKey and validatorName but use_raw_data isn't one.
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
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
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.
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 ?
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}
We miss the documentation for the OAuth2 service, if present in Apigility
Lines 42 and 55 of view/zf-apigility-documentation/operation.phtml are missing closing span tags
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.
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:
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,
),
),
)
)
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
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
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
in file /view/zf-apigility-documentation/operation.phtml on line 122
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.
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?
Route don't have have possibility of several levels for namespaces (route didn't worked with namespaces, containing %5C).
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.
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); } }
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.