Problems while trying to generate Swagger definitions in a Resteasy Project running on Wildfly

[alf]

Hi at all,

I am new to Swagger. I am facing big problems, as the documentation is not so good. I am trying to getting started with Resteasy, Swagger and Wildfly and I have many questions. I am getting the message 

I have created a very simple Rest Easy Resource looking like this:

@Path("/test")
public class testResource
{
 
 @GET
 @PermitAll
 @Produces(MediaType.APPLICATION_JSON)
 @Path("/helloWorld")
 public Response helloWorld(@QueryParam("id") Integer id,@QueryParam("name") String name)
 {
 String responseString = "id="+id+" name="+name;
 return Response.status(Status.OK).entity(responseString).build();
 }

I want to generate the Swagger definition out of it and deploy it locally on the Wildfly Server (v. 8) Now I followed exactly the steps described in the Swagger RestEasy tutorial on Github: https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-RESTEasy-2.X-Project-Setup. I added the maven dependency, I have added the resource:

 <context-param>
<param-name>resteasy.resources</param-name>
<param-value> com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON, de.test.resources </param-value>
</context-param>

The resteasy.scan-param is set true. I added to the web.xml the Swagger Servlet:

 <servlet> <servlet-name>Jersey2Config</servlet-name> <servlet-class>com.wordnik.swagger.jaxrs.config.DefaultJaxrsConfig</servlet-class> <init-param> <param-name>api.version</param-name> <param-value>1.0.0</param-value> </init-param> <init-param> <param-name>swagger.api.basepath</param-name> <param-value>http://localhost:8080/backend/rest</param-value> </init-param> <load-on-startup>2</load-on-startup> </servlet>
But unfortunately the changes according to this tutorial did not work. I downloaded the swagger resteasy sample project and added some changes according to this sample. For example, I have added the Bootstrap class.

Now, calling the URL "http://localhost:8080/backend/" (because in the the jboss-web.xml the context root is set to backend) there is the message "Can't read swagger JSON from http://localhost:8080/backend/rest/swagger.json".

I don't get how the process of the generation works and I did not find a detailed documentation of this. I don't know where the swagger.json is generated and how. I can't find the generated swagger.json file in the built target directory (also in the sample). I do not understand how I can get the annotations to my UI running on the wildfly.

Can anybody help me? I would be very grateful.

[Ron Ratovsky]

Hi,

It looks like parts of your message were cut off and it's difficult to understand what's your current state.

I'm not really sure what you've tried testing and what were the results.

The only thing you did mention is that you tried opening http://localhost:8080/backend/rest/swagger.json (I think?) and got nothing, but based on your description you should have opened http://localhost:8080/backend/swagger.json.

The swagger.json is not generated during build time and you will not find it anywhere. It's just a REST endpoint that's exposed as part of your application and generated on runtime.

If you provide more details as to what exactly you've tried and what were the exact results, we may be able to suggest further steps.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[alf]

Hi Ron,

thanks for your reply and sorry for my unclear words. There were just too many issues for me so that I did not know where to start. After trying some approaches I has worked, a Swagger UI was generated with my definitions in http://localhost:8080/backend/. But after doing some further changes in my project and performing a maven clean install, it does not work again; The swagger definition file is available under the path http://localhost:8080/backend/rest/swagger.json. But the UI does not load (as you can see in the screenshot) and in the dist directory of the target there is only the META-INF, WEB-INF Folder and the index.html, the directories images, css etc. are missing.

My web.xml looks as followed:

<?xml version="1.0"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
 <display-name>test Web Application</display-name>


 <context-param>
 <param-name>resteasy.scan</param-name>
 <param-value>true</param-value>
 </context-param>
 <context-param>
 <param-name>resteasy.servlet.mapping.prefix</param-name>
 <param-value>/rest</param-value>
 </context-param>
 <context-param>
 <!-- max size of the upload request -->
 <param-name>maxSize</param-name>
 <param-value>3145728</param-value>
 </context-param>
 <context-param>
 <!-- max size of any uploaded file -->
 <param-name>maxFileSize</param-name>
 <param-value>1024000</param-value>
 </context-param>


 <context-param>
 <param-name>resteasy.providers</param-name>
 <param-value>
 io.swagger.jaxrs.listing.ApiListingResource, io.swagger.jaxrs.listing.SwaggerSerializers,
 de.test.test.backend.service.Test1Service </param-value>
 </context-param>
 <listener>
 <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
 </listener>


 <servlet>
 <servlet-name>resteasy-servlet</servlet-name>
 <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
 <init-param>
 <param-name>javax.ws.rs.Application</param-name>
 <param-value>de.test.test.backend.service.InitApplication</param-value>
 </init-param>
 <load-on-startup>1</load-on-startup>
 </servlet>


 <servlet-mapping>
 <servlet-name>resteasy-servlet</servlet-name>
 <url-pattern>/rest/*</url-pattern>
 </servlet-mapping>


 <servlet>
 <servlet-name>DefaultJaxrsConfig</servlet-name>
 <servlet-class>io.swagger.jaxrs.config.DefaultJaxrsConfig</servlet-class>

 <init-param>
 <param-name>api.version</param-name>
 <param-value>1.0.0</param-value>
 </init-param>
 <init-param>
 <param-name>swagger.api.basepath</param-name>

 <param-value>http://localhost:8080/backend</param-value>
 </init-param>
 <init-param>
 <param-name>swagger.filter</param-name>
 <param-value>de.test.test.backend.service.ApiAuthorizationFilterImpl</param-value>

 </init-param>
 <load-on-startup>2</load-on-startup>
 </servlet>

 <filter>
 <filter-name>ApiOriginFilter</filter-name>
 <filter-class>de.test.test.backend.service.ApiOriginFilter</filter-class>
 </filter>


 <servlet>
 <servlet-name>Bootstrap</servlet-name>
 <servlet-class>de.test.test.backend.service.Bootstrap</servlet-class>
 <load-on-startup>2</load-on-startup>
 </servlet>


 <filter-mapping>
 <filter-name>ApiOriginFilter</filter-name>
 <url-pattern>/*</url-pattern>
 </filter-mapping>
 <security-constraint>
 <display-name>REST SSL</display-name>
 <web-resource-collection>
 <web-resource-name>REST Secure URLs</web-resource-name>
 <url-pattern>/*</url-pattern>
 <http-method>GET</http-method>
 <http-method>POST</http-method>
 <http-method>PUT</http-method>
 <http-method>DELETE</http-method>
 <http-method>HEAD</http-method>
 <http-method>OPTIONS</http-method>
 <http-method>TRACE</http-method>
 </web-resource-collection>
 </security-constraint>
</web-app>

I took the java classes ApiAuthorizationFilterImpl, ApiOriginFilter and Bootstrap from the Java Resteasy Sample (which you can find here: https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-RESTEasy-2.X-Project-Setup-1.5#using-swaggers-servlet-in-the-webxml ) I commented out the ApiAuthorizationFilterImpl. My pom.xml looks like this: 

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

<modelVersion>4.0.0</modelVersion>

<artifactId>test-backend</artifactId>

<packaging>war</packaging>

<name>test Backend Webapp</name>

<url>http://maven.apache.org</url>

<parent>

<groupId>de.test.test</groupId>

<artifactId>test-master</artifactId>

<version>0.0.1-SNAPSHOT</version>

<relativePath>../pom.xml</relativePath>

</parent>

<dependencies>

<!-- own dependencies -->

<dependency>

<groupId>de.test.test</groupId>

<artifactId>test-native</artifactId>

</dependency>

<!-- ... -->

<dependency>

<groupId>org.jboss.resteasy</groupId>

<artifactId>resteasy-jaxrs</artifactId>

<scope>provided</scope>

</dependency>

<dependency>

<groupId>org.jboss.resteasy</groupId>

<artifactId>resteasy-multipart-provider</artifactId>

</dependency>

<!-- Import the CDI API, we use provided scope as the API is included in 

JBoss WildFly -->

<dependency>

<groupId>javax.enterprise</groupId>

<artifactId>cdi-api</artifactId>

<scope>provided</scope>

</dependency>

<!-- Import the Common Annotations API (JSR-250), we use provided scope 

as the API is included in JBoss WildFly -->

<dependency>

<groupId>org.jboss.spec.javax.annotation</groupId>

<artifactId>jboss-annotations-api_1.2_spec</artifactId>

<scope>provided</scope>

</dependency>

<!-- Import the Servlet API, we use provided scope as the API is included 

in JBoss WildFly -->

<dependency>

<groupId>org.jboss.spec.javax.servlet</groupId>

<artifactId>jboss-servlet-api_3.1_spec</artifactId>

<scope>provided</scope>

</dependency>

<!-- Import the JPA API, we use provided scope as the API is included in 

JBoss WildFly -->

<dependency>

<groupId>org.jboss.spec.javax.transaction</groupId>

<artifactId>jboss-transaction-api_1.2_spec</artifactId>

<scope>provided</scope>

</dependency>

<!-- Import the EJB API, we use provided scope as the API is included in 

JBoss WildFly -->

<dependency>

<groupId>org.jboss.spec.javax.ejb</groupId>

<artifactId>jboss-ejb-api_3.2_spec</artifactId>

<scope>provided</scope>

</dependency>

<dependency>

<groupId>io.swagger</groupId>

            <artifactId>swagger-jaxrs</artifactId>

<version>1.5.0</version>

</dependency>

</dependencies>

<build>

<plugins>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-release-plugin</artifactId>

</plugin>

<plugin>

<groupId>org.wildfly.plugins</groupId>

<artifactId>wildfly-maven-plugin</artifactId>

<configuration>

<skip>false</skip>

<match-pattern>${project.artifactId}-.*</match-pattern>

</configuration>

</plugin>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-jar-plugin</artifactId>

<executions>

<execution>

<id>make-a-jar</id>

<phase>compile</phase>

<goals>

<goal>jar</goal>

</goals>

</execution>

</executions>

</plugin>

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-install-plugin</artifactId>

<executions>

<execution>

<phase>install</phase>

<goals>

<goal>install-file</goal>

</goals>

<configuration>

<packaging>jar</packaging>

<artifactId>${project.artifactId}</artifactId>

<groupId>${project.groupId}</groupId>

<version>${project.version}</version>

<file>${project.build.directory}/${project.artifactId}-${project.version}.jar</file>

</configuration>

</execution>

</executions>

</plugin>

<plugin>

                <groupId>com.googlecode.maven-download-plugin</groupId>

                <artifactId>download-maven-plugin</artifactId>

                <version>1.2.1</version>

                <executions>

                    <execution>

                        <id>swagger-ui</id>

                        <goals>

                            <goal>wget</goal>

                        </goals>

                        <configuration>

                            <url>https://github.com/swagger-api/swagger-ui/archive/master.tar.gz</url>

                            <unpack>true</unpack>

                            <outputDirectory>${project.build.directory}</outputDirectory>

                        </configuration>

                    </execution>

                </executions>

            </plugin>

            <plugin>

                <artifactId>maven-resources-plugin</artifactId>

                <version>2.6</version>

                <executions>

                    <execution>

                        <id>copy-resources</id>

                        <phase>validate</phase>

                        <goals>

                            <goal>copy-resources</goal>

                        </goals>

                        <configuration>

                            <outputDirectory>target/${project.artifactId}-${project.version}</outputDirectory>

                            <resources>

                                <resource>

                                    <directory>${project.build.directory}/swagger-ui-master/dist

                                    </directory>

                                    <filtering>true</filtering>

                                    <excludes>

                                        <exclude>index.html</exclude>

                                    </excludes>

                                </resource>

                            </resources>

                        </configuration>

                    </execution>

                </executions>

            </plugin>

</plugins>

</build>

</project>

How can I get the Swagger UI running correctly?

[Ron Ratovsky]

The tutorial doesn't get into how to incorporate the UI as part of your build, but it looks like you followed the samples (or some SO question).

When you build the project, make sure to include the 'package' goal as well.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[alf]

Hi Ron,

thank you very much for the quick reply, this worked for me. But now I am facing an another issue. The UI does not load my Swagger definitions, and I expect it's because the swagger.json is not complete and I don't know why. The Editor shows the following message:

Missing required property: paths

The swagger.json looks like this:

{

  "swagger": "2.0",

  "info": {

    "version": "1.0.0",

    "title": ""

  },

  "host": "localhost:8080",

  "basePath": "/backend",

  "tags": [

    {

      "name": "test"

    }

  ],

  "schemes": [

    "http"

  ]

}

The test class looks as followed:

package de.test.test.backend.service;

import javax.ws.rs.GET;

import javax.ws.rs.Path;

import javax.ws.rs.Produces;

import javax.ws.rs.core.Response;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

@Path("/test")

@Api(value = "/test", description = "Operations from test DLL")

@Produces({ "application/json", "application/xml" })

public class testService {

@GET

@Path("/WH_calculate")

@ApiOperation(value = "WH_calculate", notes = "WH_calculate.")

public Response WH_calculate() {

return null; // TODO

}

}

The web.xml parts are as followed:

<context-param>

<param-name>resteasy.providers</param-name>

<param-value> 

io.swagger.jaxrs.listing.ApiListingResource, io.swagger.jaxrs.listing.SwaggerSerializers, 

de.test.test.backend.service.testService </param-value>

</context-param>

The InitApplication:

package de.test.test.backend.service;

import java.util.HashSet;

import java.util.Set;

import javax.ws.rs.core.Application;

import io.swagger.jaxrs.config.BeanConfig;

public class InitApplication extends Application {

public InitApplication() {

BeanConfig beanConfig = new BeanConfig();

beanConfig.setVersion("1.0.2");

beanConfig.setSchemes(new String[] { "http" });

beanConfig.setHost("localhost:8080");

beanConfig.setBasePath("/backend/rest");

beanConfig.setResourcePackage("de.test.test.backend.service");

beanConfig.setScan(true);

}

@Override

public Set<Class<?>> getClasses() {

HashSet<Class<?>> set = new HashSet<Class<?>>();

set.add(testService.class);

set.add(io.swagger.jaxrs.listing.ApiListingResource.class);

set.add(io.swagger.jaxrs.listing.SwaggerSerializers.class);

return set;

}

}

Could you tell me, why the swagger.json is not generated completely? Which of these steps is not neccessary? 

[Ron Ratovsky]

Try removing the io.swagger.jaxrs.config.DefaultJaxrsConfig servlet from your web.xml. You've implemented two configuration methods instead of one.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[alf]

It works :) Thank you so much!