Skip to content

Expose Pagination in Swagger UI #2171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 11, 2018
Merged

Expose Pagination in Swagger UI #2171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3cecf04
Expose Pagination in Swagger UI
ragboyjr Aug 21, 2018
ace413d
Fix CS
dunglas Sep 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/Bridge/Symfony/Bundle/Resources/config/swagger.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@
<argument>%api_platform.collection.pagination.page_parameter_name%</argument>
<argument>%api_platform.collection.pagination.client_items_per_page%</argument>
<argument>%api_platform.collection.pagination.items_per_page_parameter_name%</argument>
<argument>%api_platform.collection.pagination.client_enabled%</argument>
<argument>%api_platform.collection.pagination.enabled_parameter_name%</argument>
<tag name="serializer.normalizer" priority="16" />
</service>

Expand Down
23 changes: 22 additions & 1 deletion src/Swagger/Serializer/DocumentationNormalizer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,13 @@ final class DocumentationNormalizer implements NormalizerInterface, CacheableSup
private $paginationPageParameterName;
private $clientItemsPerPage;
private $itemsPerPageParameterName;
private $paginationClientEnabled;
private $paginationClientEnabledParameterName;

/**
* @param ContainerInterface|FilterCollection|null $filterLocator The new filter locator or the deprecated filter collection
*/
public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, OperationMethodResolverInterface $operationMethodResolver, OperationPathResolverInterface $operationPathResolver, UrlGeneratorInterface $urlGenerator = null, $filterLocator = null, NameConverterInterface $nameConverter = null, $oauthEnabled = false, $oauthType = '', $oauthFlow = '', $oauthTokenUrl = '', $oauthAuthorizationUrl = '', array $oauthScopes = [], array $apiKeys = [], SubresourceOperationFactoryInterface $subresourceOperationFactory = null, $paginationEnabled = true, $paginationPageParameterName = 'page', $clientItemsPerPage = false, $itemsPerPageParameterName = 'itemsPerPage')
public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, OperationMethodResolverInterface $operationMethodResolver, OperationPathResolverInterface $operationPathResolver, UrlGeneratorInterface $urlGenerator = null, $filterLocator = null, NameConverterInterface $nameConverter = null, $oauthEnabled = false, $oauthType = '', $oauthFlow = '', $oauthTokenUrl = '', $oauthAuthorizationUrl = '', array $oauthScopes = [], array $apiKeys = [], SubresourceOperationFactoryInterface $subresourceOperationFactory = null, $paginationEnabled = true, $paginationPageParameterName = 'page', $clientItemsPerPage = false, $itemsPerPageParameterName = 'itemsPerPage', $paginationClientEnabled = false, $paginationClientEnabledParameterName = 'pagination')
{
if ($urlGenerator) {
@trigger_error(sprintf('Passing an instance of %s to %s() is deprecated since version 2.1 and will be removed in 3.0.', UrlGeneratorInterface::class, __METHOD__), E_USER_DEPRECATED);
Expand Down Expand Up @@ -100,6 +102,8 @@ public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFa
$this->subresourceOperationFactory = $subresourceOperationFactory;
$this->clientItemsPerPage = $clientItemsPerPage;
$this->itemsPerPageParameterName = $itemsPerPageParameterName;
$this->paginationClientEnabled = $paginationClientEnabled;
$this->paginationClientEnabledParameterName = $paginationClientEnabledParameterName;
}

/**
Expand Down Expand Up @@ -275,6 +279,9 @@ private function updateGetOperation(\ArrayObject $pathOperation, array $mimeType
$pathOperation['parameters'][] = $this->getItemsPerPageParameters();
}
}
if ($this->paginationEnabled && $resourceMetadata->getCollectionOperationAttribute($operationName, 'pagination_client_enabled', $this->paginationClientEnabled, true)) {
$pathOperation['parameters'][] = $this->getPaginationClientEnabledParameters();
}

return $pathOperation;
}
Expand Down Expand Up @@ -635,6 +642,20 @@ private function getPaginationParameters(): array
];
}

/**
* Returns enable pagination parameter for the "get" collection operation.
*/
private function getPaginationClientEnabledParameters(): array
{
return [
'name' => $this->paginationClientEnabledParameterName,
'in' => 'query',
'required' => false,
'type' => 'boolean',
'description' => 'Enable or disable pagination',
];
}

/**
* Returns items per page parameters for the "get" collection operation.
*/
Expand Down
99 changes: 99 additions & 0 deletions tests/Swagger/Serializer/DocumentationNormalizerTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1976,4 +1976,103 @@ public function testNormalizeWithPropertySwaggerContext()

$this->assertEquals($expected, $normalizer->normalize($documentation, DocumentationNormalizer::FORMAT, ['base_url' => '/app_dev.php/']));
}

public function testNormalizeWithPaginationClientEnabled()
{
$documentation = new Documentation(new ResourceNameCollection([Dummy::class]), 'Test API', 'This is a test API.', '1.2.3', ['jsonld' => ['application/ld+json']]);

$propertyNameCollectionFactoryProphecy = $this->prophesize(PropertyNameCollectionFactoryInterface::class);
$propertyNameCollectionFactoryProphecy->create(Dummy::class, [])->shouldBeCalled()->willReturn(new PropertyNameCollection(['id', 'name']));

$dummyMetadata = new ResourceMetadata('Dummy', 'This is a dummy.', 'http://schema.example.com/Dummy', [], ['get' => ['method' => 'GET', 'pagination_client_enabled' => true]]);
$resourceMetadataFactoryProphecy = $this->prophesize(ResourceMetadataFactoryInterface::class);
$resourceMetadataFactoryProphecy->create(Dummy::class)->shouldBeCalled()->willReturn($dummyMetadata);

$propertyMetadataFactoryProphecy = $this->prophesize(PropertyMetadataFactoryInterface::class);
$propertyMetadataFactoryProphecy->create(Dummy::class, 'id')->shouldBeCalled()->willReturn(new PropertyMetadata(new Type(Type::BUILTIN_TYPE_INT), 'This is an id.', true, false));
$propertyMetadataFactoryProphecy->create(Dummy::class, 'name')->shouldBeCalled()->willReturn(new PropertyMetadata(new Type(Type::BUILTIN_TYPE_STRING), 'This is a name.', true, true, true, true, false, false, null, null, ['swagger_context' => ['type' => 'string', 'enum' => ['one', 'two'], 'example' => 'one']]));
$resourceClassResolverProphecy = $this->prophesize(ResourceClassResolverInterface::class);
$resourceClassResolverProphecy->isResourceClass(Dummy::class)->willReturn(true);

$operationMethodResolverProphecy = $this->prophesize(OperationMethodResolverInterface::class);
$operationMethodResolverProphecy->getCollectionOperationMethod(Dummy::class, 'get')->shouldBeCalled()->willReturn('GET');

$operationPathResolver = new CustomOperationPathResolver(new OperationPathResolver(new UnderscorePathSegmentNameGenerator()));

$normalizer = new DocumentationNormalizer(
$resourceMetadataFactoryProphecy->reveal(),
$propertyNameCollectionFactoryProphecy->reveal(),
$propertyMetadataFactoryProphecy->reveal(),
$resourceClassResolverProphecy->reveal(),
$operationMethodResolverProphecy->reveal(),
$operationPathResolver
);

$expected = [
'swagger' => '2.0',
'basePath' => '/app_dev.php/',
'info' => [
'title' => 'Test API',
'description' => 'This is a test API.',
'version' => '1.2.3',
],
'paths' => new \ArrayObject([
'/dummies' => [
'get' => new \ArrayObject([
'tags' => ['Dummy'],
'operationId' => 'getDummyCollection',
'produces' => ['application/ld+json'],
'summary' => 'Retrieves the collection of Dummy resources.',
'parameters' => [
[
'name' => 'page',
'in' => 'query',
'required' => false,
'type' => 'integer',
'description' => 'The collection page number',
],
[
'name' => 'pagination',
'in' => 'query',
'required' => false,
'type' => 'boolean',
'description' => 'Enable or disable pagination',
],
],
'responses' => [
200 => [
'description' => 'Dummy collection response',
'schema' => [
'type' => 'array',
'items' => ['$ref' => '#/definitions/Dummy'],
],
],
],
]),
],
]),
'definitions' => new \ArrayObject([
'Dummy' => new \ArrayObject([
'type' => 'object',
'description' => 'This is a dummy.',
'externalDocs' => ['url' => 'http://schema.example.com/Dummy'],
'properties' => [
'id' => new \ArrayObject([
'type' => 'integer',
'description' => 'This is an id.',
'readOnly' => true,
]),
'name' => new \ArrayObject([
'type' => 'string',
'description' => 'This is a name.',
'enum' => ['one', 'two'],
'example' => 'one',
]),
],
]),
]),
];

$this->assertEquals($expected, $normalizer->normalize($documentation, DocumentationNormalizer::FORMAT, ['base_url' => '/app_dev.php/']));
}
}