CODEWITHSUNDEEP
javarestmavenjax-rsswagger
gvdm
gvdm

Reputation: 3156

Swagger not generating the REST documentation

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.

Upvotes: 5

Views: 6888

Answers (3)

Vinay
Vinay

Reputation: 21

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

Upvotes: 0

El Goodo
El Goodo

Reputation: 304

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 ();
    }
}

Upvotes: 5

AlexR
AlexR

Reputation: 115328

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, i.e. 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.

Upvotes: 0

Related Questions