swaggerPierwsze kroki ze swaggerem


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:

  1. 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
  2. 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
  • 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.