REST API - Swagger + Java + Jersey wrong listing path and additional apis

Question

In my project I am using Maven, Jetty, Swagger, Java and Jersey for creating REST API. I also use Swagger to create nice-looking documentation for my API.

Almost everything is ok instead three issues. At the first - this is my web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">
    <display-name>Restful Web Application</display-name>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:applicationContext.xml</param-value>
    </context-param>

    <listener>
        <listener-class>
            org.springframework.web.context.ContextLoaderListener
        </listener-class>
    </listener>

    <listener>
        <listener-class>
            org.springframework.web.context.request.RequestContextListener
        </listener-class>
    </listener>

    <servlet>
        <servlet-name>jersey-serlvet</servlet-name>
        <servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>

        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>com.pjdb.rest;com.wordnik.swagger.jaxrs;</param-value>
        </init-param>

        <init-param>
            <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
            <param-value>true</param-value>
        </init-param>

        <init-param>
            <param-name>api.version</param-name>
            <param-value>1.0</param-value>
        </init-param>

        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>http://localhost:8080/rest</param-value>
        </init-param>

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

    <servlet>
        <servlet-name>Bootstrap</servlet-name>
        <servlet-class>com.pjdb.rest.Bootstrap</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>jersey-serlvet</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>

    <filter>
        <filter-name>ApiOriginFilter</filter-name>
        <filter-class>com.pjdb.rest.utils.ApiOriginFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>ApiOriginFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

</web-app>

1) How to remove api-docs from the beginnig of listingPath?

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.1",
  "basePath": "http://localhost:8080/rest",
  "apis": [
    {
      "path": "/api-docs/resources",
      "description": ""
    },
    {
      "path": "/api-docs/employee",
      "description": ""
    }
  ]
}

And I want to remove /api-docs at the beginning of the path..

2) How can I remove "/api-docs/resources" from apis? I use only 'employee' class, not 'resources'.

3) If I type http://localhost:8080/rest/api-docs/employee I have my methods and '/' main URL which is empty. Can I remove it?

I've tried a lot of configurations. Am I missed something?

Answer 1

I'll try to answer all three of your questions, although I'm hardly a Swagger expert. I'd also suggest talking to the Swagger devs on IRC, too- they're very quick to respond. I think it's worth getting Swagger to work "automatically" so that you don't have to manually update it- that seems less than optimal to me.

1) You don't want to get rid of api-docs in your listing path- you want some sort of unique name for your listings. It doesn't have to be api-docs - for example, I use resources - but you'll need some sort of prefix to differentiate between your actual REST resources and their descriptions, on Swagger. So I don't think this is a problem at all.

2) Did you have a class that extends com.wordnik.swagger.jaxrs.JavaApiListing, perhaps called ApiResourceListing. That's where you determine the entry point to the Swagger docs. Maybe you had an extra class like this one which was pointing to /resources? (It might also be an extension of import com.wordnik.swagger.jaxrs.listing.ApiListing, which is what you use if you're not using a format suffix in your REST addresses.

3) I don't know about this one. Like I said in the beginning, maybe ask the Swagger guys on their IRC or their google group.

4) This answer is relevant for Swagger 1.2. If you've just encountered this question recently, you might want to check out the Swagger Jax-RS tutorial, which has been updated for version 1.3.

Answer 2

I've solved this in this way:

1. Save api-docs.json generated by Swagger to hard-drive
2. Edit generated JSON as you need
3. Copy this file to ~/src/main/webapp/swagger-ui/api-docs.json
4. Put http://localhost:8080/swagger-ui/api-docs.json to your discoveryUrl path in index.html of you /swagger-ui directory

This method needs from you, that you have to modify by yourself you main listing if anything change but it's safe and working solution.

My api-docs.json looks like this:

{
    "apiVersion": "1.0",
    "swaggerVersion": "1.1",
    "basePath": "http://localhost:8080/rest",
    "apis": [
        {
            "path": "/api-docs.json/employee",
            "description": ""
        }
    ]
}

and swagger-ui/index.html settings

<script type="text/javascript">
    $(function () {
        window.swaggerUi = new SwaggerUi({
            discoveryUrl:"http://localhost:8080/swagger-ui/api-docs.json",
            apiKey:"special-key",
            dom_id:"swagger-ui-container",
            supportHeaderParams: false,
            supportedSubmitMethods: ['get', 'post', 'put'],
            onComplete: function(swaggerApi, swaggerUi){
                if(console) {
                    console.log("Loaded SwaggerUI")
                    console.log(swaggerApi);
                    console.log(swaggerUi);
                }
              $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
            },
            onFailure: function(data) {
                if(console) {
                    console.log("Unable to Load SwaggerUI");
                    console.log(data);
                }
            },
            docExpansion: "none"
        });

        window.swaggerUi.load();
    });

</script>