Swagger UI with Tynamo Resteasy for Tapestry 5.4

问题:

I am using tynamo resteasy with my Tapestry 5.4 project. I'd like to incorporate Swagger to document and share API with other other teams. While I see that swagger is already in RestEasy's project dependency, it does not work "out of the box"

I've added

@Api to the "Resource" class (located in /rest/ package) and @ApiOperation to the GET method

Do I need to change AppModule or web.xml in anyway to hook the swagger UI? Is there an example (github etc.) anywhere that I can follow?

Also, will the swagger api be available at localhost/swagger/myendpoint?

回答1:

Take a look at this old commit: https://github.com/tynamo/tapestry-resteasy/commit/9a4c2979fda83900480449f25df8cb5e919e4306

Pay special attention to the SwaggerModule. The code is rather old and I'm almost sure that is not going to work out of the box if you copy&paste it as is, but it will give you a very good idea of how the connections between the projects work and the setup required.

回答2:

Here's a step by step process:

Get swagger-jaxrs: https://mvnrepository.com/artifact/io.swagger/swagger-jaxrs/1.5.0

Create a SwaggerModule.java in "modules" directory (example: com.mysite.mypkg.modules)

public class SwaggerModule {
  @Contribute(SymbolProvider.class)
  @ApplicationDefaults
  public static void provideSymbols(MappedConfiguration<String, Object> configuration) {
    configuration.add(ResteasySymbols.CORS_ENABLED, true);
  }

  @Contribute(javax.ws.rs.core.Application.class)
  public static void contributeApplication(Configuration<Object> singletons) {
    singletons.addInstance(io.swagger.jaxrs.listing.ApiListingResource.class);
    singletons.addInstance(io.swagger.jaxrs.listing.SwaggerSerializers.class);
  }

  @Startup
  public static void swagger(javax.ws.rs.core.Application application,
      BaseURLSource baseURLSource,
      @Symbol(InternalConstants.TAPESTRY_APP_PACKAGE_PARAM) String basePackage,
      @Symbol(ResteasySymbols.MAPPING_PREFIX) String restPath,
      @Symbol(SymbolConstants.APPLICATION_VERSION) String version) {
    application.getSingletons(); 
    BeanConfig config = new BeanConfig();
    config.setSchemes(new String[]{"http"});
    config.setVersion("1.0.2");
    config.setHost("localhost:8080");
    config.setBasePath("/mysite" + restPath);
    config.setTitle("Mysite Rest Documentation");
    config.setResourcePackage("com.mysite.mypkg.rest");//where your rest resources are located
    config.setScan(true);
  }

On your AppModule.java, import the SwaggerModule (Tapestry 5.4)

@ImportModule(SwaggerModule.class)
public class AppModule {...
}

The swagger.json and swagger.yaml can now be accessed as:

http://localhost:8080/mysite/rest/swagger.json

Many thanks to @ascandroli above for pointing out the basics