Dlaczego Adobe wycięło /swagger w trybie produkcyjnym?
Interfejs Swagger dostępny domyślnie pod adresem /swagger to jedno z najbardziej użytecznych narzędzi w ekosystemie Magento 2. Generuje interaktywną dokumentację REST API w oparciu o pliki webapi.xml, schematy danych i uprawnienia ACL, pozwalając na testowanie zapytań wprost z poziomu przeglądarki. Wszystko działało sprawnie do momentu premiery Magento 2.4.4, kiedy Adobe podjęło decyzję o całkowitym zablokowaniu endpointu /swagger w trybie produkcyjnym (MAGE_MODE=production). Jeśli Twój sklep działa w trybie produkcyjnym, próba wejścia pod ten adres kończy się natychmiastowym błędem 404.
Motywacja twórców była prosta: ochrona przed rekonesansem infrastruktury. Wystawiony Swagger zdradza nazwy niestandardowych modułów, parametry zapytań i strukturę danych. Problem polega na tym, że w realnym świecie e-commerce decyzja Adobe uderzyła rykoszetem w deweloperów oraz zewnętrznych integratorów. Aby przywrócić tę funkcjonalność bez kombinowania w kodzie rdzenia, stworzyliśmy darmowy moduł włączający Swagger, który oddaje pełną kontrolę nad widocznością dokumentacji w panelu administracyjnym.
Dlaczego potrzebujesz Swaggera na środowisku staging i prodzie?
Teoria architektury oprogramowania mówi, że testy integracji wykonuje się na lokalnym środowisku deweloperskim. Praktyka wdrożeń e-commerce boleśnie to weryfikuje. W 9 na 10 projektów integracyjnych – czy to z systemami ERP (Subiekt, Comarch, SAP), systemami PIM (Akeneo, Pimcore), czy platformami marketplace – zespół integratora potrzebuje dostępu do środowiska wiernie odzwierciedlającego produkcję.
Środowiska stagingowe i UAT w poprawnie skonfigurowanym procesie CI/CD pracują w trybie production. Mają wyłączone raportowanie błędów na ekranie, włączone scalanie assetów i wygenerowany kod w katalogu generated/. Przełączanie całego sklepu w tryb developer tylko po to, aby programista od ERP mógł podejrzeć schemat payloadu dla zamówień lub stanów magazynowych, mija się z celem. Prowadzi to do spadku wydajności, degradacji cache i uniemożliwia testy wydajnościowe.
Przełączanie stagingu w tryb developer psuje wiarygodność testów. Potrzebujesz trybu produkcyjnego z selektywnie odblokowaną dokumentacją REST API.
Często dochodzi też kwestia debugowania specyficznych danych produkcyjnych na zabezpieczonej kopii. Kiedy integrator pyta, dlaczego endpoint /V1/products zwraca niespodziewaną strukturę custom attributes, najszybszą drogą do weryfikacji kontraktu API jest właśnie interaktywny Swagger, a nie przeglądanie surowych plików XML w repozytorium.
Dlaczego musieliśmy sforkować moduł integer_net?
Społeczność Magento nie lubi wyważać otwartych drzwi. Kilka lat temu świetny niemiecki deweloper Andreas von Studnitz z agencji integer_net opublikował prosty moduł rozwiązujący ten problem. Niestety, w świecie Magento porzucone repozytoria to plaga. Oryginalny pakiet posiadał sztywne ograniczenia w pliku composer.json (wsparcie wyłącznie dla PHP od ~7.1 do ~8.1). W efekcie instalacja na nowoczesnym stosie technologicznym stała się niemożliwa.
Wraz z nadejściem Magento 2.4.8 i 2.4.9, gdzie standardem staje się PHP 8.3 oraz PHP 8.4, próba wykonania composer require integer-net/magento2-enable-swagger kończy się zablokowaniem drzewa zależności. Nie mogliśmy zostawić naszych klientów i partnerów integracyjnych bez działającego narzędzia.
Przygotowaliśmy publiczny, przetestowany fork modułu dostępny na naszym GitHubie: https://github.com/SISL-source/magento2-enable-swagger. Zaktualizowaliśmy definicje zależności, wyczyściliśmy deklaracje typów pod kątem PHP 8.4 i zweryfikowaliśmy pełną kompatybilność z Magento w wersji 2.4.9.
Jak działa darmowy moduł włączający Swagger w Magento 2.4.9?
Architektura modułu jest celowo minimalistyczna. Nie nadpisujemy klas rdzennych za pomocą niebezpiecznych mechanizmów preference, ani nie modyfikujemy routingu frameworka w sposób inwazyjny. Moduł wykorzystuje plugin typu around na metodzie sprawdzającej tryb działania aplikacji podczas przetwarzania żądania do kontrolera Swaggera.
Zamiast sztywnego warunku sprawdzającego zmienną środowiskową MAGE_MODE, moduł odpytuje konfigurację zapisaną w bazie (ScopeConfigInterface). W panelu administracyjnym pojawia się przejrzysty przełącznik:
- Ścieżka: Stores > Configuration > Services > Swagger > General > Enabled
- Wartość domyślna: No (bezpieczna domyślna konfiguracja)
- Opcje: Yes / No z możliwością konfiguracji na poziomie Default Config, Website lub Store View.
Dzięki temu odblokowanie Swaggera staje się decyzją administracyjną, a nie operacją wymagającą ingerencji w pliki konfiguracyjne serwera czy deployment.
Jak zainstalować i skonfigurować moduł krok po kroku?
Instalacja sprowadza się do standardowej procedury opartej o Composera i narzędzie CLI Magento. Nie wymaga żadnych niestandardowych zabiegów.
- Pobierz moduł do projektu za pomocą Composera:
composer config repositories.swagger vcs https://github.com/SISL-source/magento2-enable-swagger composer require integer-net/magento2-enable-swagger:dev-main - Włącz moduł i uruchom proces aktualizacji bazy danych:
bin/magento module:enable SISL_EnableSwagger bin/magento setup:upgrade - Jeśli pracujesz na środowisku produkcyjnym, przekompiluj kod dependency injection i wygeneruj widoki:
bin/magento setup:di:compile bin/magento setup:static-content:deploy -f - Wyczyść pamięć podręczną konfiguracji:
bin/magento cache:clean config full_page - Przejdź do Stores > Configuration > Services > Swagger, ustaw flagę na Yes i zapisz konfigurację.
Od tego momentu adres https://twoja-domena.pl/swagger renderuje pełny interfejs dokumentacji API niezależnie od wartości flagi MAGE_MODE.
Jaki jest realny kompromis bezpieczeństwa i jak go mitygować?
Nie będziemy owijać w bawełnę: Adobe zablokowało Swaggera na produkcji z konkretnego powodu. Wystawienie publicznej mapy API niesie za sobą ryzyko analityczne dla potencjalnego agresora. Swagger nie pozwala co prawda na ominięcie uwierzytelniania tokenem Bearer czy kluczem OAuth, ale podaje jak na tacy listę wszystkich zainstalowanych modułów firm trzecich i ich wersje schematów. Jeśli w jednym z nich istnieje podatność typu Zero-Day, atakujący dowie się o obecności modułu w kilka sekund.
Dlatego włączanie Swaggera na surowym środowisku produkcyjnym powinno być rozwiązaniem ostatecznym i tymczasowym. Jeśli musisz udostępnić Swaggera na produkcji lub stagingu, zastosuj przynajmniej jedną z poniższych warstw ochronnych:
- Biała lista adresów IP (Allowlist): Ogranicz dostęp do lokalizacji
/swaggeroraz powiązanego schematu/schemana poziomie serwera Nginx wyłącznie do adresów IP Twojego biura lub serwerów integratora. - Autoryzacja HTTP Basic Auth: Wymuś podanie loginu i hasła na poziomie serwera WWW przed załadowaniem zasobów Swaggera.
- Dostęp wyłącznie przez VPN: Odizoluj środowiska stagingowe od publicznego internetu, wymagając tunelu WireGuard lub OpenVPN.
Poniżej znajduje się przykładowa, skuteczna reguła dla serwera Nginx, którą warto wdrożyć w pliku konfiguracyjnym vhosta:
location ~* ^/(swagger|schema) {
allow 195.123.45.67; # IP integratora
allow 80.70.60.50; # IP biura
deny all;
try_files $uri $uri/ /index.php$is_args$args;
}Inicjatywa SISL: dlaczego reanimujemy porzucone moduły?
W SISL prowadzimy butikowe wdrożenia Magento 2 w Polsce i na co dzień zderzamy się z problemem długu technologicznego ekosystemu open source. Wiele kluczowych bibliotek narzędziowych powstało w erze Magento 2.1-2.3 i zostało porzuconych przez autorów, gdy Adobe drastycznie podniosło wymagania dotyczące wersji PHP w gałęziach 2.4.x.
Zamiast tworzyć za każdym razem prywatne obejścia zamykane w repozytoriach klientów, przyjęliśmy zasadę: bierzemy wartościowe, porzucone narzędzia, aktualizujemy je do najnowszych standardów (PHP 8.4, Magento 2.4.9), testujemy w warunkach bojowych i oddajemy społeczności za darmo na GitHubie. Uważamy, że zdrowy ekosystem Magento wymaga solidnych, bezpłatnych narzędzi diagnostycznych, które po prostu działają bez konieczności płacenia comiesięcznych abonamentów.
Jeśli Twoje wdrożenie Magento 2 wymaga nietypowej integracji API, audytu wydajnościowego lub wsparcia technicznego w architekturze backendowej, napisz do nas. Przeanalizujemy stan Twojego sklepu i zaproponujemy rozwiązania skrojone pod realne wymagania biznesowe.