Background - Swagger
Magento 2 offers several endpoints for the REST API which can be used to receive and update nearly all types of data in Magento. In fact, the REST API coverage is one of the biggest advantages of Magento 2. On top of that, the REST API framework of Magento 2 is easy to use by developers who want to provide their own API endpoints.
Swagger is a tool which is used to test REST API requests. It provides a comprehensive list of all API endpoints, including which parameters are accepted and which return values are offered.
Swagger really makes the lives of developers easier:
- when implementing their own API endpoints or
- when accessing existing API endpoints.
Swagger in Magento 2
Magento 2 has Swagger built in. If you enter https://your-store-domain.com/swagger/ in your browser, you will be able to access Swagger, pre-configured for the Magento 2 APIs. This has been possible in all Magento 2 installations up to the second to last security update. The only exceptions are if you have disabled the module or blocked the path on the web server.
In the latest security updates of Magento 2 (version 2.4.4, 2.4.3-p2, 2.3.7-p3), Swagger is disabled automatically in production mode. This means that you can still use it on development machines where it is most important, but not on the live server. It's not possible to easily use Swagger on test or staging systems either while they run in production mode (which they should).
Swagger and Security
Is Swagger a security risk? Not directly, I'd say, because it doesn't provide any additional access. All info you can see in Swagger is available via direct access too - you can do the same calls from any command line. Swagger only makes it a little easier.
But that's probably the reason why Swagger is seen as a security issue: it makes it too easy to find out
- which modules are available in a Magento 2 installation
- which information is available on public endpoints
- the exact version of Magento
- if custom endpoints exist which might not be as well secured as the core endpoints.
Thus, blocking Swagger on live instances is a good idea in my opinion.
Why would you still want to use Swagger in production mode?
The production mode is not only used on live instances, but also on staging or testing instances. And for these instances, as a developer I would like to have access to Swagger, i.e. to debug custom endpoints with real data.
Staging and testing instances are usually secured by other means, i.e. by Basic Auth or an IP restriction so not everyone has access it.
Another reason for Swagger on a staging instance: in headless projects, frontend developers might not have their own development instance, but use a testing server instead. This is the main reason why we developed a small module to enable Swagger.
The IntegerNet_EnableSwagger Magento Module
We developed an open source module which allows you to enable Swagger again in production mode. It's published on GitHub at https://github.com/integer-net/magento2-enable-swagger. You can install it on the command line via:
composer require integer-net/magento2-enable-swagger bin/magento setup:upgradeThe module provides a configuration option to either enable or disable Swagger. It is disabled by default, but can be enabled on certain instances. We suggest to save that configuration option in the app/etc/env.php file so it won't be transferred to other environments accidentally. You can do so on the command line via
bin/magento config:set --lock-env dev/swagger/active 1For security reasons, please make sure that access to Swagger is limited by other means, i.e. by basic auth or IP restriction.