swagger - empty listing with no API

Question

I am trying to use swagger in order to document my Rest APIs. I am developing a Tomcat/Spring server and the rest apis are developed using Jersey.

I following swagger guide and added the required data to my web.xml:

<servlet>
        <servlet-name>resources</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>com.wordnik.swagger.jersey.listing;app.servlet.resources.jersey;org.codehaus.jackson.jaxrs</param-value>
        </init-param>
       <init-param>
        <param-name>swagger.api.basepath</param-name>
        <param-value>http://localhost:8080/main/resources/</param-value>
        </init-param>
        <init-param>
            <param-name>api.version</param-name>
            <param-value>1</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

http://:8080/main/resources/api-docs returns the following:

{"apiVersion":"0.0","swaggerVersion":"1.2"}

Any idea what i am mising here?

Answer 1

Try to add the following to your "web.xml" (make sure you define the appropriate servlet-class locations):

<servlet>
    <servlet-name>Bootstrap</servlet-name>
    <servlet-class>com.mywebservice.utils.swagger.Bootstrap</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<filter>
    <filter-name>ApiOriginFilter</filter-name>
    <filter-class>com.mywebservice.utils.swagger.ApiOriginFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>ApiOriginFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

and make sure you have "Bootstrap", "ApiOriginFilter", "ApiListingResource" and also "ApiListingResourceJSON" (which extends ApiListing). See in the following examples of these files:

Bootstrap:

/**
 * Copyright 2012 Wordnik, Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
 * file except in compliance with the License. You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software distributed under
 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

import com.wordnik.swagger.jaxrs.JaxrsApiReader;

import javax.servlet.http.HttpServlet;

public class Bootstrap extends HttpServlet{

    private static final long serialVersionUID = 1L;

    static{
        JaxrsApiReader.setFormatString("");
    }
}

ApiOriginFilter:

import java.io.IOException;

import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletResponse;

public class ApiOriginFilter implements javax.servlet.Filter{
    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
            FilterChain chain) throws IOException, ServletException{
        HttpServletResponse res = (HttpServletResponse) response;
        res.addHeader("Access-Control-Allow-Origin", "*");
        res.addHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
        res.addHeader("Access-Control-Allow-Headers", "Content-Type");
        chain.doFilter(request, response);
    }

    @Override
    public void destroy(){
    }

    @Override
    public void init(FilterConfig filterConfig) throws ServletException{
    }
}

ApiListingResource:

import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.jaxrs.JavaApiListing;

@Path("/resources.json")
@Api("/resources")
@Produces({ "application/json"})
public class ApiListingResource extends JavaApiListing{
}

ApiListingResourceJSON:

import javax.ws.rs.Path;
import javax.ws.rs.Produces;

import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.jaxrs.listing.ApiListing;

@Path("/api-docs")
@Api("/api-docs")
@Produces({ "application/json"})
public class ApiListingResourceJSON extends ApiListing{
}

This should be it... Swagger is very nice, and once you have it set up it "just works", but to set it up one needs to do some gymnastics still.

HTH.