Using Swagger Core JAX-RS 2.0 to Generate Documentation for Existing Webservices

[Gunnar Gissel]

I am trying to use the Swagger Core JAX-RS 2.0 project to generate documentation for my existing webservices. My project is set up so the webservices are in one project and the servlets that use the webservices are in another project.

I added the dependency for swagger-jaxrs2 to both projects and added the following to the web.xml in the servlet project:

    <servlet>
    <!-- use OpenApi servlet to serve spec -->
    <servlet-name>OpenApi</servlet-name>
    <servlet-class>io.swagger.jaxrs2.integration.OpenApiServlet</servlet-class>

    <init-param>
        <param-name>openApi.configuration.resourcePackages</param-name>
        <param-value>myorg.webservices.resources,myorg.webservices.resources.subpackage1,myorg.webservices.resources.subpackage2</param-value>
    </init-param>
    <!-- alternatively specify configuration file location <init-param> <param-name>openApi.configuration.location</param-name> 
        <param-value>/openapi-configuration.json</param-value> </init-param> -->
    <!-- alternatively include a file openapi-configuration.json or openapi-configuration.yaml 
        in classpath -->

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

<servlet-mapping>
    <servlet-name>OpenApi</servlet-name>
    <url-pattern>/openapi/*</url-pattern>
</servlet-mapping>

I can run the servlet project and it works, but when I go to /openapi all I get is:

{"openapi":"3.0.0"}

I expect to instead see that and a bunch of RESTful webservice documentation stubs.

I'm clearly missing something obvious - most of the documentation is for Jersey; my project does not use Jersey or really any framework. Is there a magic annotation, or am I referring to the classes wrong, or ?

While we're on the subject, do I need to explicitly refer to subpackages, or does it recurse into subpackages?

[Francesco Tumanischvili]

Hi, 

assuming your "web services" are JAX-RS services, a setup as in your sample should work ok; a similar setup is available in sample https://github.com/swagger-api/swagger-samples/tree/2.0/java/java-jaxrs2-openapiservlet, please check it out.

Also are you using latest 2.0.0-SNAPSHOT version of swagger-jaxrs2? If not, please switch to that (available on Sonatype).

openApi.configuration.resourcePackages does indeed recurse into subpackages

[Gunnar Gissel]

I'm using resteasy, which is a jax-rs library.  My webservices are resource classes annotated with javax.ws.rs.WHATEVER annotations.  They work, I can GET/POST to them.

I'm using 2.0.0-rc1, so I'll try the snapshot.

[Gunnar Gissel]

Two followups - is there a particular reason this wouldn't work in a release candidate or stable version?

and

This is dumb, but where is the snapshot repository?  I can't resolve it automatically, so I'd need to add it to my list of repos to use it

[Francesco Tumanischvili]

As long as resources are JAX-RS annotated, this should work, RESTEast is fully supported (check out RESTEasy samples in  https:/e /github.com/swagger-api/swagger-samples/tree/2.0/java).

There have been quite some changes since rc1, so it's possible that some bug prevented it to work, while it's fixed in latest snapshot (and upcoming first release 2.0.0)

Are the resource classes available in classpath for the "swagger" web app?

Sonatype snapshot repo is the following:

<repository>
  <id>sonatype-snapshots</id>
    <name>sonatype-snapshots</name>
    <url>https://nexus.swaggerhub.com/content/repositories/sonatype-snapshots/</url>
    <snapshots>
 <enabled>true</enabled>
    </snapshots>
</repository>

[Gunnar Gissel]

I really appreciate the help, thank you

That website doesn't go anywhere for me.  I do see there is an rc2 available, so I'll try that.

I'm not sure how to tell if the resource classes are on the classpath for the swagger webapp.  I'm attempting to embed the swagger webapp in our existing webapp.

This is what my setup is - a war with servlets, the web.xml, etc.  I've added the swagger servlet to web.xml.  I've added the swagger jars to the war's lib.  I also have the jaxrs webservices I want to document in the war's lib as a jar.  The jaxrs webservices jar is on the war's classpath.

Here's an example of one of my resources:

package myorg.resources;


import a.bunch.of.stuff


@GZIP()
@Path("/Tokens")
public class TokenResource extends BaseResource {
 @Resource
 protected WebServiceContext webServiceContext;
 
 @Override
 protected String getClientAppName(){
 //impl
 }
 
 @Override
 protected WebServiceContext getWebServiceContext() {
 //impl
 }
 
 @Override
 public Logger getLogger() {
 //impl
 }
 
 @Override
 protected String getWebServiceType() {
 //impl
 }
 
 @GET
 @Path("/ForgotPassword/{userId}")
 @Produces({MediaType.APPLICATION_JSON})
 public Response getPassword(@PathParam("userId") String userId, @Context HttpServletRequest request) throws RemoteException {
 //impl
 }
 
 @POST
 @Produces({MediaType.APPLICATION_JSON})
 public Response getToken(@FormParam("userid") String userId, @FormParam("password") String password,@Context HttpServletRequest request) throws RemoteException{
 //impl
 }
}

[Francesco Tumanischvili]

Il giorno giovedì 15 marzo 2018 20:21:01 UTC+1, Gunnar Gissel ha scritto:

I really appreciate the help, thank you 

That website doesn't go anywhere for me.  I do see there is an rc2 available, so I'll try that.

Sorry my bad, correct snapshot repo, please try with 2.0.0-SNAPSHOT:

<repository>
	<id>maven-snapshots</id>
	<url>http://oss.sonatype.org/content/repositories/snapshots</url>
	<layout>default</layout>
	<releases>
	<enabled>false</enabled>
	</releases>

	<snapshots>
	<enabled>true</enabled>
	</snapshots>
	</repository>

I'm not sure how to tell if the resource classes are on the classpath for the swagger webapp.  I'm attempting to embed the swagger webapp in our existing webapp.

This is what my setup is - a war with servlets, the web.xml, etc.  I've added the swagger servlet to web.xml.  I've added the swagger jars to the war's lib.  I also have the jaxrs webservices I want to document in the war's lib as a jar.  The jaxrs webservices jar is on the war's classpath.

This sounds ok, and should pick up resources; can you maybe share your web.xml and pom? 

Nothing wrong with this resource..