From 28802f2c44dbbf29aa7f5dc80a10f44d3558f580 Mon Sep 17 00:00:00 2001 From: Alan Poulain Date: Sat, 1 Jun 2019 15:34:59 +0200 Subject: [PATCH 1/5] Compatibility with Symfony 4.3 (#1524) * Use twig instead of templating * Fix at least one suite test in Travis * Use Twig namespace (Twig > 1.10 and TwigBundle > 2.2) --- .travis.yml | 2 ++ DependencyInjection/Configuration.php | 2 +- Formatter/HtmlFormatter.php | 11 ++++++----- Resources/config/formatters.xml | 2 +- Resources/doc/configuration-reference.rst | 2 +- Resources/views/method.html.twig | 2 +- Resources/views/resource.html.twig | 4 ++-- Resources/views/resources.html.twig | 4 ++-- Tests/Formatter/testFormat-result-no-dunglas.markdown | 3 +++ Tests/Formatter/testFormat-result.markdown | 3 +++ 10 files changed, 22 insertions(+), 13 deletions(-) diff --git a/.travis.yml b/.travis.yml index 37fdc8553..3f69eaac2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,3 +1,5 @@ +dist: trusty + language: php sudo: false diff --git a/DependencyInjection/Configuration.php b/DependencyInjection/Configuration.php index 2baac26ed..c71e33000 100644 --- a/DependencyInjection/Configuration.php +++ b/DependencyInjection/Configuration.php @@ -31,7 +31,7 @@ public function getConfigTreeBuilder() ->arrayNode('motd') ->addDefaultsIfNotSet() ->children() - ->scalarNode('template')->defaultValue('NelmioApiDocBundle::Components/motd.html.twig')->end() + ->scalarNode('template')->defaultValue('@NelmioApiDoc/Components/motd.html.twig')->end() ->end() ->end() ->arrayNode('request_listener') diff --git a/Formatter/HtmlFormatter.php b/Formatter/HtmlFormatter.php index 94ab16f47..ec2c90c97 100644 --- a/Formatter/HtmlFormatter.php +++ b/Formatter/HtmlFormatter.php @@ -12,6 +12,7 @@ namespace Nelmio\ApiDocBundle\Formatter; use Symfony\Component\Templating\EngineInterface; +use Twig\Environment as TwigEnvironment; class HtmlFormatter extends AbstractFormatter { @@ -31,7 +32,7 @@ class HtmlFormatter extends AbstractFormatter protected $defaultRequestFormat; /** - * @var EngineInterface + * @var EngineInterface|TwigEnvironment */ protected $engine; @@ -113,9 +114,9 @@ public function setEnableSandbox($enableSandbox) } /** - * @param EngineInterface $engine + * @param EngineInterface|TwigEnvironment $engine */ - public function setTemplatingEngine(EngineInterface $engine) + public function setTemplatingEngine($engine) { $this->engine = $engine; } @@ -197,7 +198,7 @@ public function setDefaultSectionsOpened($defaultSectionsOpened) */ protected function renderOne(array $data) { - return $this->engine->render('NelmioApiDocBundle::resource.html.twig', array_merge( + return $this->engine->render('@NelmioApiDoc/resource.html.twig', array_merge( array( 'data' => $data, 'displayContent' => true, @@ -211,7 +212,7 @@ protected function renderOne(array $data) */ protected function render(array $collection) { - return $this->engine->render('NelmioApiDocBundle::resources.html.twig', array_merge( + return $this->engine->render('@NelmioApiDoc/resources.html.twig', array_merge( array( 'resources' => $collection, ), diff --git a/Resources/config/formatters.xml b/Resources/config/formatters.xml index 9d55d2158..54f5eb58f 100644 --- a/Resources/config/formatters.xml +++ b/Resources/config/formatters.xml @@ -21,7 +21,7 @@ - + %nelmio_api_doc.motd.template% diff --git a/Resources/doc/configuration-reference.rst b/Resources/doc/configuration-reference.rst index a4cbddb0a..d72ba35a4 100644 --- a/Resources/doc/configuration-reference.rst +++ b/Resources/doc/configuration-reference.rst @@ -8,7 +8,7 @@ Configuration Reference exclude_sections: [] default_sections_opened: true motd: - template: 'NelmioApiDocBundle::Components/motd.html.twig' + template: '@NelmioApiDoc/Components/motd.html.twig' request_listener: enabled: true parameter: _doc diff --git a/Resources/views/method.html.twig b/Resources/views/method.html.twig index efd6f6079..774cf9ff5 100644 --- a/Resources/views/method.html.twig +++ b/Resources/views/method.html.twig @@ -189,7 +189,7 @@ {{ name }} {{ infos.dataType }} - {% include 'NelmioApiDocBundle:Components:version.html.twig' with {'sinceVersion': infos.sinceVersion, 'untilVersion': infos.untilVersion} only %} + {% include '@NelmioApiDoc/Components/version.html.twig' with {'sinceVersion': infos.sinceVersion, 'untilVersion': infos.untilVersion} only %} {{ infos.description }} {% endfor %} diff --git a/Resources/views/resource.html.twig b/Resources/views/resource.html.twig index 1a51099f4..07230e2cd 100644 --- a/Resources/views/resource.html.twig +++ b/Resources/views/resource.html.twig @@ -1,11 +1,11 @@ -{% extends "NelmioApiDocBundle::layout.html.twig" %} +{% extends "@NelmioApiDoc/layout.html.twig" %} {% block content %}
      • - {% include 'NelmioApiDocBundle::method.html.twig' %} + {% include '@NelmioApiDoc/method.html.twig' %}
    diff --git a/Resources/views/resources.html.twig b/Resources/views/resources.html.twig index 997153dba..a6d2ca78a 100644 --- a/Resources/views/resources.html.twig +++ b/Resources/views/resources.html.twig @@ -1,4 +1,4 @@ -{% extends "NelmioApiDocBundle::layout.html.twig" %} +{% extends "@NelmioApiDoc/layout.html.twig" %} {% block content %}
    @@ -33,7 +33,7 @@
    • {% for data in methods %} - {% include 'NelmioApiDocBundle::method.html.twig' %} + {% include '@NelmioApiDoc/method.html.twig' %} {% endfor %}
    • diff --git a/Tests/Formatter/testFormat-result-no-dunglas.markdown b/Tests/Formatter/testFormat-result-no-dunglas.markdown index c22632cba..3baba524e 100644 --- a/Tests/Formatter/testFormat-result-no-dunglas.markdown +++ b/Tests/Formatter/testFormat-result-no-dunglas.markdown @@ -622,6 +622,9 @@ dependency_type[a]: _This method is useful to test if the getDocComment works._ +This method is useful to test if the getDocComment works. +And, it supports multilines until the first '@' char. + #### Requirements #### **id** diff --git a/Tests/Formatter/testFormat-result.markdown b/Tests/Formatter/testFormat-result.markdown index 068d0f21d..deb85f286 100644 --- a/Tests/Formatter/testFormat-result.markdown +++ b/Tests/Formatter/testFormat-result.markdown @@ -706,6 +706,9 @@ dependency_type[a]: _This method is useful to test if the getDocComment works._ +This method is useful to test if the getDocComment works. +And, it supports multilines until the first '@' char. + #### Requirements #### **id** From ad836eaa7ac1832e1865ae0203cc4ea422178771 Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Fri, 24 Jul 2020 16:50:43 +0200 Subject: [PATCH 2/5] Updates links in the README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a9da1b193..49a5c530c 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,14 @@ for your APIs. Documentation ------------- -[Read the documentation on symfony.com](https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html) +[Read the documentation on symfony.com](https://symfony.com/doc/2.x/bundles/NelmioApiDocBundle/index.html) Contributing ------------ See -[CONTRIBUTING](https://github.com/nelmio/NelmioApiDocBundle/blob/master/CONTRIBUTING.md) +[CONTRIBUTING](https://github.com/nelmio/NelmioApiDocBundle/blob/2.x/CONTRIBUTING.md) file. From 2b3952350862bc09e7fa355d520e4ad68733b392 Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Fri, 24 Jul 2020 16:54:00 +0200 Subject: [PATCH 3/5] Update installation instructions --- Resources/doc/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst index 360404a08..1c1033999 100644 --- a/Resources/doc/index.rst +++ b/Resources/doc/index.rst @@ -15,7 +15,7 @@ following command to download the latest stable version of this bundle: .. code-block:: bash - $ composer require nelmio/api-doc-bundle + $ composer require nelmio/api-doc-bundle:^2.0 This command requires you to have Composer installed globally, as explained in the `installation chapter`_ of the Composer documentation. From b54c4933ef78099e32b22418bfb4ac4d14f3c010 Mon Sep 17 00:00:00 2001 From: mantis Date: Fri, 25 Jan 2019 17:17:45 +0000 Subject: [PATCH 4/5] Fix: Deprecation: A tree builder without a root node is deprecated since symfony 4.2 (#1457) * Fix: Deprecation: A tree builder without a root node is deprecated since Symfony 4.2 and will not be supported anymore in 5.0. * Fix: Deprecation: A tree builder without a root node is deprecated since Symfony 4.2 and will not be supported anymore in 5.0. --- DependencyInjection/Configuration.php | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/DependencyInjection/Configuration.php b/DependencyInjection/Configuration.php index c71e33000..a2cecf6a1 100644 --- a/DependencyInjection/Configuration.php +++ b/DependencyInjection/Configuration.php @@ -18,9 +18,16 @@ class Configuration implements ConfigurationInterface { public function getConfigTreeBuilder() { - $treeBuilder = new TreeBuilder(); - $treeBuilder - ->root('nelmio_api_doc') + $treeBuilder = new TreeBuilder('nelmio_api_doc'); + + if (method_exists($treeBuilder, 'getRootNode')) { + $rootNode = $treeBuilder->getRootNode(); + } else { + // symfony < 4.2 support + $rootNode = $treeBuilder->root('nelmio_api_doc'); + } + + $rootNode ->children() ->scalarNode('name')->defaultValue('API documentation')->end() ->arrayNode('exclude_sections') From 46e50f73803d2db10f8b39751f69168bb7b4f2a8 Mon Sep 17 00:00:00 2001 From: jeremy <62880356+copiri-six@users.noreply.github.com> Date: Tue, 19 Oct 2021 08:33:29 -0400 Subject: [PATCH 5/5] Minor grammatical changes (#1887) Minor changes to improve the grammar of this docs page. --- Resources/doc/swagger-support.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Resources/doc/swagger-support.rst b/Resources/doc/swagger-support.rst index a4b23b95b..fd09295e3 100644 --- a/Resources/doc/swagger-support.rst +++ b/Resources/doc/swagger-support.rst @@ -8,7 +8,7 @@ based on ``@ApiDoc`` annotations, which can be used for consumption by Annotation options ------------------ -A couple of properties has been added to ``@ApiDoc``: +Several properties have been added to ``@ApiDoc`` to provide this feature: To define a **resource description**:: @@ -49,9 +49,9 @@ Multiple response models ------------------------ Swagger provides you the ability to specify alternate output models for -different status codes. Example, ``200`` would return your default resource object -in JSON form, but ``400`` may return a custom validation error list object. This -can be specified through the ``responseMap`` property:: +different status codes. For example: ``200`` would return your default resource object +in JSON form, while ``400`` may return a custom validation error list object. This +can be specified using the ``responseMap`` property:: /** * @ApiDoc( @@ -79,7 +79,7 @@ when this endpoint returns a ``400 Validation failed.`` HTTP response. .. note:: You can omit the ``200`` entry in the ``responseMap`` property and specify - the default ``output`` property instead. That will result on the same thing. + the default ``output`` property instead. That will result in the same response. Integration with ``swagger-api/swagger-ui`` ------------------------------------------- @@ -93,7 +93,7 @@ You could import the routes for use with `swagger-ui`_. resource: "@NelmioApiDocBundle/Resources/config/swagger_routing.yml" prefix: /api-docs -Et voila!, simply specify http://yourdomain.com/api-docs in your ``swagger-ui`` +Et voila! Simply specify http://yourdomain.com/api-docs in your ``swagger-ui`` instance and you are good to go. .. note:: @@ -118,7 +118,7 @@ To dump just the resource list: $ php app/console api:swagger:dump --list-only -To dump just the API definition the ``users`` resource: +To dump just the API definition of the ``users`` resource: .. code-block:: bash