With the Eclipse-Microprofile framework you can develop microservices quite easy. One of the build-in functionalities is the support for the OpenAPI standard. This means your REST services will automatically exposed in a OpenAPI format. For example on a Payara-Micro Server a rest service resource /api/training/ may look like this:
openapi: 3.0.0 info: title: Deployed Resources version: 1.0.0 servers: - url: http://localhost:8080 paths: /api/training: post: operationId: getSomeData requestBody: content: application/xml: schema: $ref: '#/components/schemas/XMLConfig' responses: default: description: Default Response. content: application/xml: schema: type: object components: schemas: XMLConfig: ....
You can request the OpenAPI resource form your server running your REST service:
The Swagger UI is a web interface which can be used to interact with your REST API providing the OpenAPI standard. This is a nice feature, with is for example a build-in functionality from OpenLiberty. But also on other Microprofile Servers like Wildfly or Payara you can add the Swagger UI easily. Just add the following maven dependency into your microservice:
.... <dependency> <groupId>org.microprofile-ext.openapi-ext</groupId> <artifactId>openapi-ui</artifactId> <version>1.1.3</version> </dependency> ...
This will automatically activate the swagger web UI. To access the UI from your web browser just open the resource /openapi-ui/
If you are running your service in Docker, which is likely to be the case in most projects, you will need to overwrite the Docker internal host name. Within Eclipse Microprofile, this is very easy via the config API. You simply need to set the following environment variable:
version: "3.3" services: my-service: image: .... environment: MP_OPENAPI_SERVERS: "http://localhost:8080" ....
You can also add multiple server instances by seperating with comma. You will find a complete a list of configurable items for the OpenAPI in the MicroProfile OpenAPI Specification.