昂首阔步不生成REST文档

Question

I'm trying to let Swagger autogenerate che documentation of my REST APIs but I only get a partial result.

I'm using Resteasy. I added the Maven Swagger dependency

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jaxrs</artifactId>
    <version>1.5.3</version>
</dependency>

Then I configured my Application object

package com.myapp.init;


import java.util.HashSet;
import java.util.Set;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

import io.swagger.jaxrs.config.BeanConfig;
import io.swagger.jaxrs.listing.ApiListingResource;
import io.swagger.jaxrs.listing.SwaggerSerializers;


@ApplicationPath("/rest")
public class WebappInit extends Application {

    public WebappInit() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("theIP:8080");
        beanConfig.setBasePath("/myapp/rest/");
        beanConfig.setResourcePackage("the.resource.package");
        beanConfig.setScan(true);
        beanConfig.setPrettyPrint(true);

    }


    public Set<Class<?>> getClasses() {
        Set<Class<?>> s = new HashSet<Class<?>>();


        // here I add my REST WSs
        s.add(ApiListingResource.class);
        s.add(SwaggerSerializers.class);


        return s;
    }

}

Then I run the web application (on a Wildfly 9 server) and go to the URL http://localhost:8080/myapp/rest/swagger.json . That's what I get

{
  swagger: "2.0",
  info: {
    version: "1.0.0"
  },
  host: "10.17.36.215:8080",
  basePath: "/devops/rest/",
  schemes: [
    "http"
  ]
}

It seems that Swagger cannot build the REST documentation, even though my REST endpoints are reachable and are added to the Swagger list of resources.

What can be the problem?

Thank you

Giulio

Update: I checked that in the Swagger init method BeanConfig.classes() my REST classes are correctly discovered.

Answer 1

You need to add an @Api annotation to your resource classes.

For example:

package my.sample;
import io.swagger.annotations.Api;
import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.core.Response;

@Api
@Path ("/mypath")
public class MyResource
{
    @GET
    public Response myEndpoint()
    {
        return Response.ok ();
    }
}

Answer 2

I think I got your problem. Your root service extends Application that allows dynamic building of your resources hierarchy. I believe that swagger even cannot support this technique because it generates its metadata (json files) at compile time.

I always use annotation based REST services, ie each resource is annotated with appropriate @Path annotation. The framework initializes all resources automatically, so I do not have to extend my root resource from Application and implement getClasses() . In this case swagger can extract all your resources and generate json files at compile time by analyzing of JAXRS annotations like @Path , @PathParam , @GET , @POST etc.

Answer 3

You have to add @Api annotation to your resource class and load the resource package in setResourcePackage method. It should do the magic.