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:
- Plik swagger wersja swagger-ST-221.yaml
- Plik swagger wersja swagger-ST-215.yaml
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