swagger Samouczek
Pierwsze kroki ze swaggerem
Szukaj…
Uwagi
Ta sekcja zawiera przegląd tego, czym jest swagger i dlaczego deweloper może chcieć go użyć.
Powinien również wymieniać wszelkie duże tematy w swagger i link do powiązanych tematów. Ponieważ Dokumentacja dotycząca swagger jest nowa, może być konieczne utworzenie początkowych wersji tych pokrewnych tematów.
Wprowadzenie - instalacja - konfiguracja (programowanie w Node.js)
Wprowadzenie:
Swagger to zestaw reguł / specyfikacji dla formatu opisującego interfejsy API REST. Zapewnia potężny i aktywnie rozwijany ekosystem narzędzi wokół tej formalnej specyfikacji, takich jak generatory kodu i edytory. Najlepszą częścią Swagger jest to, że dokumentacja metod, parametrów i modeli jest ściśle zintegrowana z kodem serwera, dzięki czemu interfejsy API mogą być zawsze zsynchronizowane. Oto link dający krótki przegląd tego, co jest swagger: pierwsze kroki.
Pisanie specyfikacji:
Specyfikacje można zapisać w JSON lub YAML. I tak tworzymy odpowiednio plik swagger.json lub swagger.yaml. Do utworzenia pliku można użyć edytora online. Oto link opisujący składnię specyfikacji: http://swagger.io/specification/
Sposoby użycia swagger:
- Podejście oparte na API (podejście z góry na dół): Użyj edytora swagger → Napisz definicje swagger → Użyj swagger-codegen i swagger-ui do generowania interfejsów API
- Pierwsze podejście do usługi (podejście oddolne): Opracuj klasy zasobów JAX-RS za pomocą adnotacji swagger → Użyj rdzenia swagger, aby automatycznie wygenerować definicje swagger → Używając swagger-codegen i swagger-ui do generowania interfejsów API i dokumentacji klienta. Powyższe można wykonać podczas kompilacji maven podczas wtyczki Swagger maven.
Instalacja i konfiguracja
W tej sekcji zainstalujemy swagger, skonfigurujemy interfejs użytkownika swagger i wygenerujemy z niego serwer i klient SDK. Aby zainstalować swagger za pomocą menedżera pakietów Node, wykonaj następujące polecenie:
npm install -g swagger
Użycie flagi „-g” zapewni, że moduł zostanie zainstalowany globalnie. Następnie utworzymy projekt za pomocą następującego polecenia:
swagger project create <project-name>
To poprosi użytkownika o wybranie frameworka do opracowania interfejsów API REST. Można wybrać opcję Express. Spowoduje to utworzenie katalogu projektu z następującymi elementami i plikiem README.md w każdym z nich:
- api /
- kontrolery /
- pomocnicy /
- kpiny /
- wywyższać się/
- config /
- test/
- api /
- kontrolery /
- pomocnicy
- api /
- app.js
- pakiet.json
Serwer jest teraz w zasadzie gotowy i można go uruchomić za pomocą tego polecenia, które zostanie wykonane w katalogu głównym projektu:
swagger project start
Jeśli serwer hosta jest ustawiony jako localhost a numer portu nie jest modyfikowany w pliku app.js , serwer jest uruchamiany pod http://localhost:10010 Teraz interfejs użytkownika swagger można wykorzystać do dalszego rozwoju naszych interfejsów API REST. Można to uruchomić w nowym terminalu za pomocą:
swagger project edit
Otworzy się edytor swagger w zakładce przeglądarki na losowo wygenerowanym porcie. Przykładowe żądanie powitania GET można już zobaczyć w pliku swagger.yaml. Wszelkie dalsze zmiany w tym pliku spowodują ponowne uruchomienie serwera.
W sekcji ścieżek wartością używaną dla x-swagger-router-controller powinna być nazwa pliku javascript w folderze kontrolery. Na przykład hello_world.js powinien znajdować się w katalogu kontrolerów. Ponadto wartość parametru operationId reprezentuje nazwę funkcji w powyższym pliku javascript. To tutaj należy zapisać logikę biznesową. Tak więc nasza konfiguracja swagger jest kompletna i może być wykorzystana do dalszego rozwoju naszego API.