Ten fragment kodu to Swagger Specification w wersji 2.0, czyli format dokumentacji dla API. Zawiera on informacje dotyczące API, takie jak opis, wersja, nazwa, host i ścieżka bazowa.
W sekcji „tags” znajdują się kategorie, które mogą być użyte do grupowania ścieżek, a w „paths” znajdują się konkretne ścieżki dostępne w API. W tym przykładzie jest tylko jedna ścieżka „/ApiService.asmx/Execute”, która obsługuje żądania typu POST.
W sekcji „parameters” znajduje się jeden parametr „body”, który jest obiektem typu „ApiExecuteRequest” i jest przekazywany w żądaniu POST. W sekcji „responses” opisane są odpowiedzi serwera dla każdego możliwego przypadku, takie jak „200” dla udanego wykonania żądania, „401” dla nieprawidłowych danych uwierzytelniających i „400” dla nieprawidłowych danych żądania.
Swagger jest bardzo przydatnym narzędziem do dokumentowania API i pomaga programistom w łatwym zrozumieniu, testowaniu i korzystaniu z API.
Informacje ogólne dotyczące WS
Swagger
Pobierz plik w formacie swagger i go rozpakuj
Następnie załaduj go na stronie: https://editor.swagger.io/
Historia zmian:
dpmag
Ten fragment kodu przedstawia ścieżkę API „/dpmag.asmx/GetDocumentsByAwizo” w specyfikacji Swagger 2.0.
Powyżej w definicji zostały zadeklarowane tagi, które identyfikują tę ścieżkę jako część modułu „DPMAG”.
W tej ścieżce została zdefiniowana operacja „post”, która umożliwia pobieranie dokumentów na podstawie numeru awizo.
W sekcji „parameters” zostały zadeklarowane cztery parametry: „body” typu „AuthData” zawierający dane autoryzacyjne, „nrawizo” typu „string” zawierający numer awizo oraz opcjonalne parametry „pageSize” i „pageNumber”, które ograniczają liczbę dokumentów zwracanych w odpowiedzi.
W sekcji „responses” zostały zadeklarowane trzy możliwe odpowiedzi na żądanie API: „200” w przypadku sukcesu, „401” w przypadku nieprawidłowych danych autoryzacyjnych i „400” w przypadku nieprawidłowych danych żądania.
Sekcja „schema” określa format danych zwracanych w odpowiedzi - w tym przypadku są to dokumenty zdefiniowane w modelu „DPMAG_DocumentResponse”.
GetDocumentsByCustomer
Ten fragment dokumentacji opisuje endpoint o nazwie /dpmag.asmx/GetDocumentsByCustomer, który obsługuje żądanie typu POST.
Opis tego endpointu jest podzielony na sekcje:
tags- tagi, którymi endpoint jest oznaczony (w tym przypadku „DPMAG”)summary- krótki opis endpointu („Get documents”)description- dłuższy opis, który w tym przypadku jest pusty („”)operationId- unikalny identyfikator endpointu („GetDocumentsByCustomer”)consumes- formaty danych, które są obsługiwane przez endpoint (w tym przypadku „application/json”)produces- formaty danych, które mogą być zwracane przez endpoint (w tym przypadku również „application/json”)parameters- lista parametrów, które endpoint przyjmuje, w tym:body- ciało żądania w formacie JSON, które zawiera dane uwierzytelniające („AuthData”), potrzebne do autoryzacji użytkownikanridodn- numer identyfikacyjny klienta, dla którego mają być zwrócone dokumenty (wymagany)ean- kod kreskowy dokumentu (opcjonalny)dateFrom- data początkowa zakresu dat, dla którego mają być zwrócone dokumenty (opcjonalny)dateTo- data końcowa zakresu dat, dla którego mają być zwrócone dokumenty (opcjonalny)pageSize- liczba wyników na stronę (opcjonalny)pageNumber- numer strony (opcjonalny)
responses- lista możliwych odpowiedzi, w tym:- kod „200” z opisem „Success”, który oznacza, że żądanie zostało przetworzone poprawnie i zwrócone zostały oczekiwane dane w formacie JSON, którego schemat odpowiada definicji „DPMAG_DocumentResponse”
- kod „401” z opisem „Invalid authentication data”, który oznacza, że żądanie nie zawiera poprawnych danych uwierzytelniających
- kod „400” z opisem „Invalid request data”, który oznacza, że żądanie zawiera nieprawidłowe dane.
AddOrder
Endpoint dpzle.asmx/AddOrder to metoda API, która umożliwia dodanie zamówienia do systemu. Jest to żądanie POST, które akceptuje ładunek JSON w ciele żądania zawierający niezbędne informacje do utworzenia zamówienia. API wymaga, aby dane uwierzytelniające były zawarte w nagłówkach żądania w celu autoryzacji.
Endpoint jest oznaczony jako część interfejsu API „DPZLE” i ma podsumowanie „Add order”. Konsumuje i produkuje dane w formacie JSON oraz ma jeden parametr w ciele żądania o typie DPZLE_AddOrderRequest. Odpowiedź ma kod stanu 200 w przypadku sukcesu, a schemat odpowiedzi to DPZLE_AddOrderResponse.
Jeśli dane uwierzytelniające są nieprawidłowe lub wystąpią jakieś problemy z danymi żądania, API zwróci odpowiedź z kodem stanu 401 lub 400 odpowiednio, wraz z komunikatem błędu w treści odpowiedzi.
Rola WMS
default.asmx
Adres testowy dla programisty
/App_webService/wms/default.asmx
Przykładowa witryna:
https://root.softwarestudio.com.pl/app_webservice/wms/default.asmx
Zawiera metody testowe tzw „lustro”, czyli metodę do wywołania, która jednak nic nie zapisuje w bazie danych
HelloWorld
Funkcja do sprawdzenia komunikacji, zwraca tekst
{ „message”: „Hello World!” }
https://root.softwarestudio.com.pl/app_webservice/wms/default.asmx/helloworld
Wyjątkowa funkcja, która nie wymaga danych przesyłanych w BODY, w tym uwierzytelniania.
AddAssortment
Test poprawności wywołania metody dodawania asortymentu do bazy:
https://root.softwarestudio.com.pl/app_webservice/wms/default.asmx/AddAssortment
Przykładowa zawartość BODY
knaso.asmx
Zawiera zestaw funkcji logicznie powiązanych z kartotekami towarowymi - asortymentowymi.
AddAssortment
Pozwala na dopisywanie nowych kartotek towarowych do bazy
https://root.softwarestudio.com.pl/app_webservice/wms/knaso.asmx/AddAssortment
BODY zawierać musi dwie sekcje:
- authData - dane autoryzacyjne
- addAssortmentData - dane związane z zakładaną kartoteką
Przykład BODY
Przykład zwracanego poprawnego komunikatu:
gdzie
- refno - zwraca unikalny wewnętrzny identyfikator dodanej kartoteki towarowej.
- name - nazwa wywołanej funkcji
- number - liczba określająca status
- seen - data i czas wykonania
GetAssortment
Funkcja zwraca dane dotyczące asortymentu wraz ze stanem magazynowym oraz stanem dostępnym.
https://root.softwarestudio.com.pl/app_webservice/wms/knaso.asmx/GetAssortment
Wymagane jest podanie identyfikatora SKU, symbol magazynu oraz oddziału.
Zawartość BODY:
Przykład poprawnych danych zwracanych przez web metodę:
GetStock
Funkcja zwraca tablicę danych, aktywnych kartotek towarowych oraz ich stany zapasów magazynowych. Wynik jest filtrowany wg magazynu i oddziału. Zwraca są wyłącznie te pozycje, których stan jest różnych od zera.
Pozycje zerowe (brak stanu lub stan=0) nie są zwracane.
https://root.softwarestudio.com.pl/app_webservice/wms/knaso.asmx/GetStock
Zawiera sekcje:
- authData
- StockData
Przykładowa zawartość BODY:
gdzie:
- Nridasn - unikalny, wewnętrzny identyfikator kartoteki systemu WMS
- Sku - identyfikator jawny kartoteki magazynowej tzw indeks materiałowy
- Name - nazwa artykułu
- Stock - zapas magazynowy w momencie zwraca danych
kncrm.asmx
Zawiera zestaw funkcji logicznie powiązanych z kartotekami klientów - odbiorców.
AddContractor
Pozwala na dopisywanie nowych kartotek odbiorców do bazy
https://root.softwarestudio.com.pl/app_webservice/wms/kncrm.asmx/AddContractor
- authData - dane autoryzacyjne
- ContractorData- dane związane z zakładaną kartoteką
- refno - zwraca unikalny wewnętrzny identyfikator dodanej kartoteki kontrahenta.
- name - nazwa wywołanej funkcji
- number - liczba określająca status
- seen - data i czas wykonania
dpzle.asmx
Zawiera zestaw funkcji związanych z zamówieniami (awizacjami) dostaw i wysyłek.
AddOrder
Pozwala na dopisywanie nowych kartotek odbiorców/dostawców do bazy wraz z zamówieniem
https://root.softwarestudio.com.pl/app_webservice/wms/dpzle.asmx/AddOrder
BODY zawierać musi sekcje:
- authData - dane autoryzacyjne
- ContractorData- dane związane z zakładaną kartoteką
- OrderData - dane nagłówkowe zamówienia/zlecenia
- OrderPositions - lista pozycji zamówienia
- refno - zwraca unikalny wewnętrzny identyfikator dodanego dokumentu zamówienia.
- name - nazwa wywołanej funkcji
- number - liczba określająca status
- seen - data i czas wykonania
Dokumentacja techniczna StudioSystem. Pytania wdrożeniowe: kontakt z SoftwareStudio.