RESTEasy > Blogs > Sample Project For Swagger And JAX-RS Integration

Sample Project For Swagger And JAX-RS Integration

By Wei Nan Li | May 22, 2020

Recently we have received(thanks Moicen for contribution) an example showing how to integrate Swagger and RESTEasy together, and here is the link:

• resteasy-examples/jaxrs-swagger-example at 4.2.0.Final · resteasy/resteasy-examples · GitHub

This example shows how to integrate Swagger and JAX-RS implementation and use them together. The JAX-RS implementation we use here is RESTEasy.

To use the Swagger for the restful resources, we need to generate the JSON file needed by Swagger firstly. And here is the command to do so:

$ mvn compile

The above command will invoke the swagger-maven-plugin defined in pom.xml, and it will generate the JSON file target/swagger/jaxrs-api.json needed by Swagger.

The content of the generated file is shown like the following content:

{
  "openapi": "3.0.1",
  "info": {
    "title": "RESTEasy Swagger Example",
    "description": "JAX-RS API Document",
    "termsOfService": "https://example.com",
    "contact": {
      "email": "example@example.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "1.0"
  },
  "paths": {
    "/dummy": {
      "get": {
        "tags": [
          "dummy"
        ],
        "summary": "get dummy",
        "description": "Get Dummy",
        "operationId": "get",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

The above file will be used by the Swagger UI server. The Swagger community has provided a docker image to run the Swagger UI server here:

• swagger-ui

To use the above docker image, you need to install the Docker engine in your local machine, and then run the following command firstly to fetch the image:

$ docker pull swaggerapi/swagger-ui
...
Status: Downloaded newer image for swaggerapi/swagger-ui:latest
docker.io/swaggerapi/swagger-ui:latest

As the command and result shown above, we have fetched the swagger-ui container. The next step is to create the container from the image, and here is the command to do so:

$ docker run -itd -v $(pwd)/target/swagger:/swagger -e SWAGGER_JSON=/swagger/jaxrs-api.json -p 8888:8080 swaggerapi/swagger-ui

Please note the above command need to be run in this sample’s project directory. The reason is that the container needs the generated jaxrs-api.json in the project directory, so we mapped it into the container in above command.

After running above command, we can see a swagger-ui container is running, and here is the docker command to verify it:

$ docker ps
CONTAINER ID        IMAGE                                 COMMAND                  CREATED             STATUS              PORTS                            NAMES
d3f923c815cf        swaggerapi/swagger-ui                 "sh /usr/share/nginx…"   14 seconds ago      Up 13 seconds       80/tcp, 0.0.0.0:8888->8080/tcp   exciting_ellis

From above command output we can see the the swagger-ui service is mapped to 8888 port, and we can access it to see its output:

As the screenshot shown above, we can see the Swagger UI is running, and it exposes a dummy resource.

Now we can start our JAX-RS service in the example backed by embedded Jetty server defined in pom.xml. Here is the command to do so:

$ mvn jetty:run
...
[INFO] Started Jetty Server

As the command output shown above, the Jetty server is started. And now we can go back at Swagger UI window, and try to invoke the dummy service:

After clicking the Try it out as shown above, we can see the result like this:

As we can see, in the Swagger UI it has generated the curl command to call the service. Unfortunately the result is 404 Not found, and this is because the port number in the URL is 8888 instead of 8080. Because we are running our real service in 8080, so we can fix the port in the URL and manually invoke the curl command as Swagger UI provided to us. Here is the command to do so:

$ curl -X GET "http://localhost:8080/dummy" -H "accept: */*"
dummy

From above command and its output, we can see our service is invoked.