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
{
"authData": {
"login": "A83F-EF35E9409C3B",
"password": "B4D35813-8815-4393"
},
"addAssortmentData":{
"nridodn": "3331111551110",
"sku": "12137",
"ean":"123",
"name": "SIEMEK5",
"warehouse": "01",
"unit": "szt.",
"department": "POP"
}
}
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
{
"authData": {
"login": "A83F-EF35E9409C3B",
"password": "B4D35813-8815-4393"
},
"addAssortmentData":{
"nridodn": "3331111551110",
"sku": "12137",
"ean":"123",
"name": "SIEMEK5",
"warehouse": "01",
"unit": "szt.",
"department": "POP"
}
}
Przykład zwracanego poprawnego komunikatu:
{
"ssResponseData": {
"refno": 6374699774045181,
"name": "AddAssortment",
"number": 0,
"seen": "2021-01-23T11:22:20.7122745+01:00"
}
}
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:
{
"authData": {
"login": "A83F-EF35E9409C3B",
"password": "B4D35813-8815-4393"
},
"addAssortmentData":{
"sku": "88552266",
"warehouse": "01",
"department": "CEN"
}
}
Przykład poprawnych danych zwracanych przez web metodę:
{
"assortmentData": {
"sku": "88552266",
"name": "Zdolny 8-latek: przygoda z matematyką 88552266/11 ",
"department": "CEN",
"warehouse": "01",
"unit": "SZT",
"nridodn": 2361080250356,
"ean": "",
"sku2": "88552266/11",
"productNetWeight": 0.000,
"productGrossWeight": 10525.000,
"productWidth": 0.0,
"productHeight": 0.0,
"productLength": 0.0,
"productCapacity": 0.0,
"productDescription": "",
"nridasn": 4038150830498,
"productStock": 220.000,
"productStockAvailable": 228.000
}
}
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:
{
"authData": {
"login": "A83F-EF35E9409C3B",
"password": "B4D35813-8815-4393"
},
"stockData":{
"warehouse": "01",
"department": "CEN"
}
}
Przykład poprawnych danych zwracanych przez web metodę:
{
"authData": null,
"stockData": {
"department": "CEN",
"warehouse": "01",
"productStock": [{
"nridasn": 5245202251509,
"sku": "0101010101099",
"name": "Uszczelki '555' DMWMS912032019309 ",
"stock": 1.000
},
{
"Nridasn": 5245202002499,
"Sku": "11111111111",
"Name": "tryby 2222222222 ",
"Stock": 100.000
},
{
"Nridasn": 6365359512997772,
"Sku": "112233",
"Name": "Torba lażowa",
"Stock": 1066.490
},
{
"Nridasn": 4154082220412,
"Sku": "885522/1101WMS",
"Name": "Zdolny 8-latek: przygoda z matematyką 885522/11 ",
"Stock": 220.000
},
{
"Nridasn": 4038150830498,
"Sku": "88552266",
"Name": "Zdolny 8-latek: przygoda z matematyką 88552266/11 ",
"Stock": 220.000
},
{
"Nridasn": 4135080455066,
"Sku": "987",
"Name": "Gra video",
"Stock": 206.000
},
{
"Nridasn": 4161135653869,
"Sku": "C7",
"Name": "Telewizor kolorowy",
"Stock": 303.000
}
]
}
}
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
BODY zawierać musi dwie sekcje:
- authData – dane autoryzacyjne
- ContractorData- dane związane z zakładaną kartoteką
Przykład BODY
{
"authData": {
"login": "A83F-EF35E9409C3B",
"password": "B4D35813-8815-4393"
},
"contractorData":{
"contractorPrx": "01",
"department": "CEN",
"nridodn":"6245103610848",
"contractorName":"nazwa pełna",
"contractorShortName":"nazwa skrocona",
"contractorCountry":"PL",
"contractorPostcode":"12-345",
"contractorCity":"Miejscowość",
"contractorStreet":"Ulica",
"contractorPhoneNumber":"+48 11 22 33 444",
"contractorMail":"mail@wms.net.pl",
"contractorVAT":"PL7791010701",
"contractorDescription":"uwagi, opis kartoteki"
}
}
Przykład zwracanego poprawnego komunikatu:
{
"ssResponseData": {
"refno": 6245103610848,
"name": "AddContractor",
"number": 0,
"seen": "2021-01-24T09:10:52.5637389+01:00"
}
}
gdzie
- 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
Przykład BODY
{
"authData":{
"login":"A83F-EF35E9409C3B",
"password":"B4D35813-8815-4393"
},
"contractorData":{
"contractorPrx":"01",
"contractorName":"ContractorName SS",
"contractorShortName":"ContractorShortName",
"contractorCountry":"pl",
"contractorPostcode":"12345",
"contractorCity":"ContractorCity",
"contractorStreet":"ContractorStreet",
"contractorPhoneNumber":"ContractorPhoneNumber",
"contractorMail":"ContractorMail",
"contractorVAT":"ContractorVAT",
"contractorDescription":"ContractorDescription"
},
"orderData":{
"department":"CEN",
"warehouse":"MG",
"nridodn":"3035164709144",
"orderPrx":"01",
"orderType":"ZPZ",
"orderNumber":"Numer 2021",
"orderPositions":[{"orderPositionSku":"0101010101099",
"orderQuantity":1234,
"orderPalletNumber":"AA123"
},
{"orderPositionSku":"9879871",
"orderQuantity":1235,
"orderPalletNumber":"BB123"
}
]
}
}
Przykład zwracanego poprawnego komunikatu:
{
"ssResponseData": {
"refno": 6245103610848,
"name": "AddOrder",
"number": 0,
"seen": "2021-01-24T09:10:52.5637389+01:00"
}
}
gdzie:
- 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