Wprowadzenie interfejsów REST API w CEE

Spis treści

Aby umożliwić generowanie i wyświetlanie REST API w CEE, wprowadzono dwa nowe interfejsy:

Swagger Service
Swagger UI

Wprowadzone interfejsy

Swagger Service

Usługa sieciowa z endpointem do generowania pliku swagger.json, dostępna pod ścieżką:

„/services/rest/com.cisag.sys.tools.swagger.rest.SwaggerService/swagger”

Endpoint zwraca dokumentację wszystkich dostępnych endpointów REST API w formacie określonym przez specyfikację OpenAPI.

Swagger UI

Aplikacja internetowa dostępna pod ścieżką:

/swagger

Aplikacja pobiera dokumentację w formacie JSON z Swagger Service i wyświetla ją w formie graficznej.

Wyświetlane endpointy

Do wygenerowanej dokumentacji włączane są wszystkie endpointy, które występują w aplikacjach z kategorii Web Service, z określonym specjalnym przeznaczeniem REST Service.

Uwaga

Swagger nie dokumentuje punktów BIS ani innych automatycznie generowanych endpointów.

Struktura

Sekcja Servers zawiera listę adresów serwerów używanych jako prefiksy do wysyłania zapytań przez Swagger API.

W obecnej wersji każdy adres serwera zawiera wbudowaną bazę danych OLTP, która obsługuje wysyłane zapytania.

Uwaga

Przed wysłaniem zapytań należy:

uruchomić aktywną sesję w danej bazie danych z poziomu Comarch ERP Enterprise UI
w przypadku braku aktywnej sesji zwracany jest błąd:
Cannot set OLTP database for an existing session without database

Endpointy API

Endpointy REST są pogrupowane według swoich usług. Każdy punkt zawiera:

względną ścieżkę zapytania,
parametry zapytania,
treść zapytania
możliwe odpowiedzi

Ścieżka zapytania

Reprezentuje względną ścieżkę endpointu – jest połączeniem ścieżki usługi i ścieżki endpointu.

/services/rest/com.cisag.sys.tools.swagger.rest.SwaggerService/swagger

Parametry zapytania

Jeżeli endpoint przyjmuje parametry, są one wyświetlane w sekcji Parameters. Dla każdego parametru podawane są:

nazwa,
typ,
źródło (path, query, header, cookie),
informacja, czy jest wymagany.

Przykład

Obecnie w Swagger każdy zadeklarowany parametr jest oznaczony jako wymagany.

Parametry nie wymagają dodatkowych adnotacji. Implementacja Swagger wykorzystuje adnotacje już używane w definicjach parametrów w usługach sieciowych.

Treść zapytania

Ta sekcja przedstawia strukturę i format treści zapytania przekazywanego do endpointu

Treść zapytania nie wymaga dodatkowych adnotacji.
Implementacja zawiera dodatkową adnotację: com.cisag.sys.tools.swagger.annotations.RequestBody, która może być użyta do opisu treści zapytania.
Adnotację należy stosować dla parametru reprezentującego treść zapytania.

Odpowiedzi
Ta sekcja przedstawia możliwe odpowiedzi, które użytkownik może otrzymać z endpointu.
Każda odpowiedź musi zawierać:

kod odpowiedzi,
opis.

Odpowiedź może również zawierać przykład treści odpowiedzi.

Definiowanie odpowiedzi, w tym dodanie przykładu treści, wymaga zdefiniowania w kodzie z użyciem dodatkowych adnotacji.

Wymagane adnotacje:

io.swagger.annotations.ApiResponses — kontener wszystkich definicji odpowiedzi dla endpointu

io.swagger.annotations.ApiResponse — definicja pojedynczej odpowiedzi API

Wykorzystywane pola

Pole	Typ	Opis	Wymagane
code	int	Kod odpowiedzi	Nie
message	string	Opis odpowiedzi	Nie
response	class	Typ treści odpowiedzi	Tak
responseContainer	string	Kontener treści odpowiedzi (wartości: Set, List)	Tak

Przykład użycia:

Przykład

@GET
@Path(„swagger”)
@ApiResponses({
@ApiResponse(code=200, message = Successful generation of json file, response = Specification.class),
@ApiResponse(code=403, message = Not enough privileges),
@ApiResponse(code=500, message = Error occurred during loading classes)
})
@Produces(„application/json”)
public Response exampleMethod(){
// Method definition
}

Format treści odpowiedzi

Przypisywany z adnotacji javax.ws.rs.Produces.
Jeśli brak adnotacji, domyślnie ustawiany jest format application/json.

Schematy

Jeżeli generator napotka obiekt złożony, jest on zapisywany jako obiekt schematu, a w innych miejscach odwołuje się do niego przez referencję.
Obiekt schematu zawiera pełną rekurencyjną strukturę obiektu.
Oznaczenie [] przy typie pola (np. [string]) definiuje tablicę.
Tryb testowy

Swagger UI udostępnia tryb testowania endpointu, aktywowany przyciskiem [Try it out].

Po uruchomieniu trybu testowego zarówno treść zapytania, jak i wszystkie parametry stają się edytowalne.

Wysłanie zapytania odbywa się przyciskiem [Execute].
Bazowy URL zapytania jest ustalany na podstawie wybranego serwera w sekcji Servers.
Wszystkie wymagane parametry muszą być uzupełnione przed wysłaniem zapytania.
Anulowanie trybu testowego odbywa się przyciskiem [Cancel].

Przykład trybu testowego

Endpoint bez parametrów ani treści zapytania:

Endpoint z parametrami i treścią zapytania:

Przykładowa odpowiedź: