Skip to content

Commit 19140a5

Browse files
DjordyKoertDjordyKoert
authored
docs(routing): PHP config & scalar UI (#2720)
## Description Updates routing documentation to: - show both PHP & yaml format - configuration for scalar #2718 Also removed `config/routing/scalar.php` in favour of users of the bundle manually defining their routes ## What type of PR is this? (check all applicable) - [ ] Bug Fix - [ ] Feature - [ ] Refactor - [ ] Deprecation - [ ] Breaking Change - [x] Documentation Update - [ ] CI ## Checklist - [ ] I have made corresponding changes to the documentation (`docs/`)
1 parent ca8530d commit 19140a5

3 files changed

Lines changed: 126 additions & 71 deletions

File tree

‎config/routing/scalar.php‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

‎docs/areas.rst‎

Lines changed: 69 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -38,34 +38,75 @@ Your main documentation is under the ``default`` area. It's the one shown when a
3838

3939
Then update your routing to be able to access your different documentations:
4040

41-
.. code-block:: yaml
42-
43-
# app/config/routing.yaml
44-
app.swagger_ui:
45-
path: /api/doc/{area}
46-
methods: GET
47-
defaults: { _controller: nelmio_api_doc.controller.swagger_ui, area: default }
48-
49-
# With Redocly UI
50-
# app/config/routing.yaml
51-
#app.redocly:
52-
# path: /api/doc/{area}
53-
# methods: GET
54-
# defaults: { _controller: nelmio_api_doc.controller.redocly, area: default }
55-
56-
# With Stoplight
57-
# app/config/routing.yaml
58-
#app.stoplight:
59-
# path: /api/doc/{area}
60-
# methods: GET
61-
# defaults: { _controller: nelmio_api_doc.controller.stoplight, area: default }
62-
63-
# To expose them as JSON
64-
#app.swagger.areas:
65-
# path: /api/doc/{area}.json
66-
# methods: GET
67-
# defaults: { _controller: nelmio_api_doc.controller.swagger }
41+
.. configuration-block::
6842

43+
.. code-block:: yaml
44+
45+
# config/routes/nelmio_api_doc.yaml
46+
app.swagger_ui:
47+
path: /api/doc/{area}
48+
methods: GET
49+
defaults: { _controller: nelmio_api_doc.controller.swagger_ui, area: default }
50+
51+
# With Redocly UI (use instead of Swagger UI)
52+
# app.redocly:
53+
# path: /api/doc/{area}
54+
# methods: GET
55+
# defaults: { _controller: nelmio_api_doc.controller.redocly, area: default }
56+
57+
# With Stoplight (use instead of Swagger UI)
58+
# app.stoplight:
59+
# path: /api/doc/{area}
60+
# methods: GET
61+
# defaults: { _controller: nelmio_api_doc.controller.stoplight, area: default }
62+
63+
# With Scalar (use instead of Swagger UI)
64+
# app.scalar:
65+
# path: /api/doc/{area}
66+
# methods: GET
67+
# defaults: { _controller: nelmio_api_doc.controller.scalar, area: default }
68+
69+
# To expose them as JSON
70+
# app.swagger.areas:
71+
# path: /api/doc/{area}.json
72+
# methods: GET
73+
# defaults: { _controller: nelmio_api_doc.controller.swagger, area: default }
74+
75+
.. code-block:: php
76+
77+
// config/routes/nelmio_api_doc.php
78+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
79+
80+
return static function (RoutingConfigurator $routes): void {
81+
$routes->add('app.swagger_ui', '/api/doc/{area}')
82+
->controller('nelmio_api_doc.controller.swagger_ui')
83+
->methods(['GET'])
84+
->defaults(['area' => 'default']);
85+
86+
// With Redocly UI
87+
// $routes->add('app.redocly', '/api/doc/{area}')
88+
// ->controller('nelmio_api_doc.controller.redocly')
89+
// ->methods(['GET'])
90+
// ->defaults(['area' => 'default']);
91+
92+
// With Stoplight
93+
// $routes->add('app.stoplight', '/api/doc/{area}')
94+
// ->controller('nelmio_api_doc.controller.stoplight')
95+
// ->methods(['GET'])
96+
// ->defaults(['area' => 'default']);
97+
98+
// With Scalar
99+
// $routes->add('app.scalar', '/api/doc/{area}')
100+
// ->controller('nelmio_api_doc.controller.scalar')
101+
// ->methods(['GET'])
102+
// ->defaults(['area' => 'default']);
103+
104+
// To expose them as JSON
105+
// $routes->add('app.swagger.areas', '/api/doc/{area}.json')
106+
// ->controller('nelmio_api_doc.controller.swagger')
107+
// ->methods(['GET'])
108+
// ->defaults(['area' => 'default']);
109+
};
69110
70111
That's all! You can now access ``/api/doc/internal``, ``/api/doc/commercial`` and ``/api/doc/store``.
71112

@@ -92,7 +133,7 @@ Then add the attribute before your controller or action::
92133

93134
.. code-block:: php-attributes
94135
95-
use Nelmio\Attribute as Nelmio;
136+
use Nelmio\ApiDocBundle\Attribute as Nelmio;
96137
97138
/**
98139
* All actions in this controller are documented under the 'internal' area

‎docs/index.rst‎

Lines changed: 57 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -37,31 +37,66 @@ Open a command console, enter your project directory and execute the following c
3737
3838
By default, only routes under ``/api`` are documented. Update the regexp at ``nelmio_api_doc.areas.path_patterns`` in ``config/packages/nelmio_api_doc.yaml`` to change this policy.
3939

40-
To browse your documentation with a UI, you need to enable a UI route. If you're using **Flex**, the installer created a ``config/routes/nelmio_api_doc.yaml`` file with a JSON route enabled and the UI route commented out. Uncomment the UI of your choice (Swagger UI requires the ``twig`` and ``asset`` packages):
40+
To browse your documentation with a UI, you need to enable a UI route. If you're using **Flex**, the installer should have created a ``config/routes/nelmio_api_doc.yaml`` file with a JSON route enabled and the UI route commented out. Uncomment the UI of your choice (all UIs require the ``twig`` and ``asset`` packages):
4141

42-
.. code-block:: yaml
42+
.. configuration-block::
43+
44+
.. code-block:: yaml
45+
46+
# config/routes/nelmio_api_doc.yaml
47+
app.swagger:
48+
path: /api/doc.json
49+
methods: GET
50+
defaults: { _controller: nelmio_api_doc.controller.swagger }
51+
52+
# Uncomment one of the following to enable a documentation UI:
53+
app.swagger_ui:
54+
path: /api/doc
55+
methods: GET
56+
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
57+
58+
# app.redocly:
59+
# path: /api/doc
60+
# methods: GET
61+
# defaults: { _controller: nelmio_api_doc.controller.redocly }
62+
63+
# app.stoplight:
64+
# path: /api/doc
65+
# methods: GET
66+
# defaults: { _controller: nelmio_api_doc.controller.stoplight }
67+
68+
# app.scalar:
69+
# path: /api/doc
70+
# methods: GET
71+
# defaults: { _controller: nelmio_api_doc.controller.scalar }
72+
73+
.. code-block:: php
74+
75+
// config/routes/nelmio_api_doc.php
76+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
77+
78+
return static function (RoutingConfigurator $routes): void {
79+
$routes->add('app.swagger', '/api/doc.json')
80+
->controller('nelmio_api_doc.controller.swagger')
81+
->methods(['GET']);
4382
44-
# config/routes/nelmio_api_doc.yaml
45-
app.swagger:
46-
path: /api/doc.json
47-
methods: GET
48-
defaults: { _controller: nelmio_api_doc.controller.swagger }
83+
// Uncomment one of the following to enable a documentation UI:
84+
$routes->add('app.swagger_ui', '/api/doc')
85+
->controller('nelmio_api_doc.controller.swagger_ui')
86+
->methods(['GET']);
4987
50-
# Uncomment one of the following to enable a documentation UI:
51-
app.swagger_ui:
52-
path: /api/doc
53-
methods: GET
54-
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
88+
// $routes->add('app.redocly', '/api/doc')
89+
// ->controller('nelmio_api_doc.controller.redocly')
90+
// ->methods(['GET']);
5591
56-
# app.redocly:
57-
# path: /api/doc
58-
# methods: GET
59-
# defaults: { _controller: nelmio_api_doc.controller.redocly }
92+
// $routes->add('app.stoplight', '/api/doc')
93+
// ->controller('nelmio_api_doc.controller.stoplight')
94+
// ->methods(['GET']);
6095
61-
# app.stoplight:
62-
# path: /api/doc
63-
# methods: GET
64-
# defaults: { _controller: nelmio_api_doc.controller.stoplight }
96+
// $routes->add('app.scalar', '/api/doc')
97+
// ->controller('nelmio_api_doc.controller.scalar')
98+
// ->methods(['GET']);
99+
};
65100
66101
.. note::
67102

@@ -99,7 +134,7 @@ routes that are documented by configuring the bundle:
99134
100135
.. tip::
101136

102-
`Twig <https://symfony.com/components/Twig%20Bundle>`_ and `Assets <https://symfony.com/components/asset>`_ packages are needed to use swagger ui.
137+
`Twig <https://symfony.com/components/Twig%20Bundle>`_ and `Assets <https://symfony.com/components/asset>`_ packages are needed to use any of the documentation UIs (Swagger UI, Redocly, Stoplight, Scalar).
103138

104139
How does this bundle work?
105140
--------------------------
@@ -108,7 +143,7 @@ It generates an OpenAPI documentation from your Symfony app thanks to
108143
**Describers**. One extracts data from SwaggerPHP attributes, one from your
109144
routes, etc.
110145

111-
If you configured the ``app.swagger_ui`` route above, you can browse your
146+
If you configured one of the UI routes above (e.g. ``app.swagger_ui``), you can browse your
112147
documentation at ``http://example.org/api/doc``.
113148

114149
Using the bundle

0 commit comments

Comments
 (0)