Explorer
Introduction
The Explorer service provides a central UI for all accessible REST interfaces of ApiOmat. The UI is based on Swagger UI and provide a user friendly way to interacts with all REST resources.
Explorer retrieve service information from the available Consul discovery. It use these information to query every of the available services (YAMBAS, all its modules and micro-services) in order to generate a single OpenAPI specification :
As default, Explorer service will be available under the following :
|
Port |
8094 |
|
Context path |
/apidocs |
|
Host |
Installation
Please refer to the [Explorer] Installation.
Usage
Provide and hide REST endpoints to Explorer
In order to be able to see your own REST endpoints in Explorer different things are required. Your service needs to be registered to consul discovery service and needs to provide a swagger.json on the endpoint "/{contextPath}/v2/api-docs".
Depending on your service implementation you can provide the swagger endpoint in different ways. E.g. for Spring Boot Application you can add the maven dependency io.springfox:springfox-swagger2 and define a SwaggerConfiguration annotating it with @EnableSwagger2 .
To be able to explicitly hide the endpoints on Explorer you just need to add the following tag to your service configuration (application.yml):
-
spring.cloud.consul.discovery.tags: hiddenAPI
In that way the service is registered to consul, has its own endpoint for providing swagger.json but actually is not shown in Explorer.
Application-specific API Docs
The Explorer service also provides an application-specific API documentation which already contains the application name, the module name and the data model name of all available REST endpoints.
One of the advantages of the application-specific apidocs is that you have quick access to your available data model endpoints to manipulate your application data.
The generic apidocs view is still available by selecting "all applications" from list. To access the application specific apidocs you simply fill in your credentials, select your application from list and click on the refresh button:
OpenAPI 2.0
The application-specific apidocs are based on a generated OpenAPI 2.0 JSON which is accessible via following REST endpoint:
