Über generische OpenAPI Dokumente können verschiedene REST Client automatisiert erstellt werden, z. B. JavaScript, Java oder C#. Das OpenAPI Dokument ist ein JSON Dokument und beschreibt die API formal.
OpenAPI Dokument
Um auf das OpenAPI Dokument der AMPAREX API zuzugreifen, dient folgender Link:
https://<host>/amparex/webaxapi/v2/api-docs
oder
http://<host>:8080/amparex/webaxapi/v2/api-docs
Je nach Server muss <host> durch den Server (z. B. preview1) ersetzt werden. Das Ergebnis ist ein JSON Dokument, das aus dem Browser kopiert werden muss:
Bitte beachten Sie, dass der Zugriff auf das OpenAPI Dokument nur auf Testservern funktioniert.
Dieses JSON Dokument ist die Beschreibung der AMPAREX API und kann z. B. für SwaggerHub verwendet werden.
SwaggerHub
Nun benötigt man noch das Swagger Tool 'Swagger-UI', um die API zu visualisieren. Dazu sind folgende Schritte nötig:
Beschreibung | |
---|---|
(01) Account unter SwaggerHub anlegen. (02) Bei SwaggerHub einloggen. (03) Neue API erstellen. | |
(04) Dialog wie nebenstehend ausfüllen (05) Create API klicken. (06) Nun öffnet sich die Swagger-UI mit dem OpenAPI Editor. Im linken Teil befindet sich der Editor und im rechten Teil die Dokumentation der API. | |
(07) Nun das zuvor kopierte OpenAPI JSON Dokument von der URL 'http://localhost:8080/amparex/webaxapi/v2/api-docs' in das linke Editor-Fenster kopieren. (08) Die Frage, ob von JSON in XAML konvertiert werden soll, mit 'JA' bestätigen. | |
(09) Nun wird rechts in der Vorschau die API Dokumentation angezeigt. (10) Dieses Dokument ist die Dokumentation der API. Im oberen Teil befinden sich die einzelnen Zugriffsmethoden der API. Im unteren Teil ist das Modell, d. h. die Entitäten (z. B. Artikel) beschrieben. | |
(11) Im Kopfmenü von SwaggerHub gibt es eine Download-Schaltfläche. Über diese kann einfach ein RestClient Projekt erstellt werden, mit dem komfortabel die API verwendet werden kann. (12) Dort sind die verschiedensten Sprachen zu finden. In unserem Beispiel wird ein Java Client erstellt. | |
(13) Das erstellte Zip File wird gespeichert. (14) Das Projekt kann in einer Java Entwicklungsumgebung geöffnet werden. Am besten erstellt man sich daraus ein JAR File. | |
(15) Eine 'Test Main Klasse' zeigt die Verwendung des Rest-Java-Clients Rest Client Verwendung import io.swagger.client.api.ArticlesApi; import io.swagger.client.api.LoginApi; import io.swagger.client.model.*; import java.util.List; public class Main { public static void main(String[] args) throws Exception { // Configuration LoginApi loginApi = new LoginApi(); ApiClient apiClient = loginApi.getApiClient(); apiClient.setBasePath("https://preview8.amparex.net/amparex/webaxapi"); // base path, set hosthere apiClient.setConnectTimeout(3 * 1000); // 3 seconds apiClient.setReadTimeout(30 * 1000); // 30 seconds apiClient.setWriteTimeout(10 * 1000); // 10 seconds // use your user, password and alias here // login and get security token (Bearer token) SecToken secTokenWrap = loginApi.getSecTokenUsingPOST("tester", "tester!8X", "pa-a-ffh6ioqxzje-ceabuy_dtzdvp_h0hwjitjvyls="); String secToken = secTokenWrap.getValue(); // create search query for articles ArticleSearchQuery articleSearchQuery = new ArticleSearchQuery(); articleSearchQuery.setName("Ace"); SearchQueryMetaData searchQueryMetaData = new SearchQueryMetaData(); searchQueryMetaData.setLimit(10); searchQueryMetaData.setPage(1); articleSearchQuery.setMetaData(searchQueryMetaData); // search articles ArticlesApi articlesApi = new ArticlesApi(); apiClient.setApiKey("Bearer " + secToken); ListResultWrapperArticleOverview listResultWrapperArticleOverview = articlesApi.searchArticlesUsingPOST("pa-a-ffh6ioqxzje-ceabuy_dtzdvp_h0hwjitjvyls=",articleSearchQuery); List<ArticleOverview> list = listResultWrapperArticleOverview.getResult(); for (ArticleOverview articleOverview : list) { System.out.println(articleOverview); } } } |