Cannot access swagger documentation using <url>/api-docs

Question

I'm trying to build Hello World REST service using Jersey and swagger to generate the documentation. I'm able to invoke the rest methods successfully, but when I try to access the swagger documentation by calling:

http://localhost:8080/com.swagger.first/rest/api-docs

I get '404 Not found'. (I tried also to add .json to the end)

I followed the steps in this tutorial to build my service.

My web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app 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"
version="3.0">
<display-name>com.swagger.first</display-name>
<servlet>
    <servlet-name>Jersey REST Service</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>
            com.wordnik.swagger.jaxrs.json,
            com.swagger.first
        </param-value>
    </init-param>
    <init-param>
        <param-name>jersey.config.server.provider.classnames</param-name>
        <param-value>
            com.wordnik.swagger.jersey.listing.ApiListingResourceJSON,
            com.wordnik.swagger.jersey.listing.JerseyApiDeclarationProvider,
            com.wordnik.swagger.jersey.listing.JerseyResourceListingProvider
        </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Jersey REST Service</servlet-name>
    <url-pattern>/rest/*</url-pattern>
</servlet-mapping>

<servlet>
    <servlet-name>Jersey2Config</servlet-name>
    <servlet-class>com.wordnik.swagger.jersey.config.JerseyJaxrsConfig</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/com.swagger.first/rest</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

and here is my pom.xml:

<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/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.swagger.first</groupId>
<artifactId>com.swagger.first</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>war</packaging>
<build>
    <sourceDirectory>src</sourceDirectory>
    <plugins>
        <plugin>
            <artifactId>maven-war-plugin</artifactId>
            <version>2.6</version>
            <configuration>
                <warSourceDirectory>WebContent</warSourceDirectory>
                <failOnMissingWebXml>false</failOnMissingWebXml>
            </configuration>
        </plugin>
        <plugin>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.3</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
    </plugins>
</build>
<dependencies>
    <dependency>
        <groupId>com.wordnik</groupId>
        <artifactId>swagger-jersey2-jaxrs_2.10</artifactId>
        <version>1.3.12</version>
    </dependency>
</dependencies>

and finally, here is my service class:

package com.swagger.first;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;
import io.swagger.annotations.*;


@Api( value="hello", description="HelloWrold service")
@Path("/hello")
public class HelloWorld {

@GET
@Produces(MediaType.TEXT_PLAIN)
@ApiOperation(value="Returns 'Hello World!!' string", notes="No comment")
@ApiResponse(code=200, message="Succeeded")
public String helloWorld(){
    return "Hello World!!";
}

@GET
@Produces(MediaType.APPLICATION_XML)
@ApiOperation(value="Returns 'Hello World!!' string as XML", notes="No comment")
@ApiResponses(value = {
        @ApiResponse(code=200, message="Succeeded"),
        @ApiResponse(code=400, message="Testing Swagger")
        })
public String helloWorldXml(){
    return "<hello> Hello World!! </hello>";
}

@GET
@Produces(MediaType.TEXT_PLAIN)
@Path("/echo")
@ApiOperation(value="Returns the query param", notes="No comment")
public String echoStringQueryParam(@ApiParam(name="s", value="any string", required=true) @QueryParam("s") String s){
    return s;
}
}

Answer 1

Thanks Alexender for sharing this important information, here is another link to follow when starting up https://hub.packtpub.com/restful-java-web-services-swagger/ and after you are able to get swagger spec in something like swagger.json format as mentioned in this tutorial link then i guess one should follow steps mentioned in alexender's reply to get the final beautiful swagger documentation.

Answer 2

Although this solution comes late I am hoping it will come in handy to people who are currently looking for answers to this problem.

The Jersey/Swagger tutorial that you referenced fails to mention that the user interface for Swagger is not included in the maven install. What it does at its core is generate a swagger.json file that is ready to be consumed by the Swagger UI

If you are looking for API docs like the ones displayed here: http://petstore.swagger.io/ ,

Then you need to install the following npm package and copy over its contents to your webapp folder in your java project. https://www.npmjs.com/package/swagger-ui-dist

Your basic project structure should look something like this:

You also need to edit the index.html file so that the url variable that is defined there is linked to your local swagger.json file instead of the petstore example that is set there by default.

In my case it looked like this:

 <script>
window.onload = function() {

  // Build a system
  const ui = SwaggerUIBundle({
    url: "http://localhost:8080/simple-service-webapp/api/swagger.json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

  window.ui = ui
}

After it's deployed, you should be able to see the documentation when you access the root url of your application in a browser