在springboot中整合jersey和springfox-swagger2

前言

为了实现RESTful Webservice和接口说明，基于springboot平台，使用jersey作为JAX-RS的实现，采用swagger文档在线生成工具。

提要

在实现了springboot集成jersey的swagger文档功能，同时满足SpringMVC 整合swagger提供RESTful文档功能。

• Springboot  集成swagger 通过springfox-swagger2实现SpringMVC的RESTful文档接口服务；

• Springboot  集成 Jersey 通过swagger-jersey2-jaxrs 实现Jersey的文档接口服务；

 

环境

Springboot  1.5.1.RELEASE

springfox-swagger 2 2.6.1

swagger  1.5.12

 

详细配置

1、Pom文件

    < properties >
        < project.build.sourceEncoding >UTF-8 project.build.sourceEncoding >
        < swagger.version >1.5.12 swagger.version >
        < springfox-swagger2.version >2.6.1 springfox-swagger2.version >
        < spring.boot.version >1.5.1.RELEASE spring.boot.version >
    properties >

    < repositories >
        < repository >
            < id >spring-releases id >
            < url >https://repo.spring.io/libs-release url >
        repository >
    repositories >

    < parent >
        < groupId >org.springframework.boot groupId >
        < artifactId >spring-boot-starter-parent artifactId >
        < version >1.5.1.RELEASE version >
    parent >

    < dependencies >
        < dependency >
            < groupId >org.springframework.boot groupId >
            < artifactId >spring-boot-starter-web artifactId >
        dependency >

        < dependency >
            < groupId >org.webjars groupId >
            < artifactId >webjars-locator artifactId >
            < version >0.32 version >
            < exclusions >
                < exclusion >
                    < groupId >org.apache.commons groupId >
                    < artifactId >commons-lang3 artifactId >
                exclusion >
            exclusions >
        dependency >


        < dependency >
            < groupId >org.springframework.boot groupId >
            < artifactId >spring-boot-starter-jersey artifactId >
        dependency >
        < dependency >
            < groupId >io.swagger groupId >
            < artifactId >swagger-jersey2-jaxrs artifactId >
            < version >${swagger.version} version >
        dependency >

        < dependency >
            < groupId >org.webjars groupId >
            < artifactId >swagger-ui artifactId >
            < version >2.2.10 version >
        dependency >
        < dependency >
            < groupId >org.glassfish.hk2 groupId >
            < artifactId >spring-bridge artifactId >
            < version >2.5.0-b34 version >
        dependency >




        < dependency >
            < groupId >io.swagger groupId >
            < artifactId >swagger-annotations artifactId >
            < version >${swagger.version} version >
        dependency >
        < dependency >
            < groupId >io.swagger groupId >
            < artifactId >swagger-models artifactId >
            < version >${swagger.version} version >
        dependency >
        < dependency >
            < groupId >io.springfox groupId >
            < artifactId >springfox-swagger2 artifactId >
            < version >${springfox-swagger2.version} version >
        dependency >
        < dependency >
            < groupId >io.springfox groupId >
            < artifactId >springfox-swagger-ui artifactId >
            < version >${springfox-swagger2.version} version >
        dependency >





        < dependency >
            < groupId >org.springframework.boot groupId >
            < artifactId >spring-boot-starter-test artifactId >
            < scope >test scope >
        dependency >


    dependencies >
    < build >
        < finalName >${project.artifactId} finalName >
        < plugins >
            < plugin >
                < groupId >org.springframework.boot groupId >
                < artifactId >spring-boot-maven-plugin artifactId >
                < version >${spring.boot.version} version >
                < configuration >
                    < mainClass >sample.rs.service.SampleRestApplication mainClass >
                configuration >
                < executions >
                    < execution >
                        < goals >
                            < goal >repackage goal >
                        goals >
                    execution >
                executions >
            plugin >
        plugins >
    build >

2、springboot配置文件 application.properties

 server.servlet-path = /
 spring.jersey.application-path = /api

3、springboot启动class

import  org.springframework.boot.SpringApplication;
import  org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public  class  SampleRestApplication {

    public  static  void  main(String[] args) {
        SpringApplication.run(SampleRestApplication. class , args);
    }
}

4、Jersey配置类，整合swagger

import  javax.annotation.PostConstruct;

import  org.glassfish.jersey.server.ResourceConfig;
import  org.glassfish.jersey.server.wadl.internal.WadlResource;
import  org.springframework.beans.factory.annotation.Value;
import  org.springframework.stereotype.Component;

import  io.swagger.jaxrs.config.BeanConfig;
import  io.swagger.jaxrs.listing.ApiListingResource;
import  io.swagger.jaxrs.listing.SwaggerSerializers;
import  sample.jersey.demo1.HelloResource;
import  sample.jersey.demo1.JerseyTest;
import  sample.jersey.demo2.Endpoint;
import  sample.jersey.demo2.ReverseEndpoint;
import  sample.jersey.demo3.HelloService;

@Component
public  class  JerseyConfig  extends  ResourceConfig {

    @Value ( "${spring.jersey.application-path}" )
    private  String apiPath;

    public  JerseyConfig() {
        register(Endpoint. class );
        register(ReverseEndpoint. class );
        this .registerEndpoints();
    }

    @PostConstruct
    public  void  init() {
        // Register components where DI is needed
        this .configureSwagger();
    }

    private  void  registerEndpoints() {
        this .register(HelloResource. class );
        this .register(JerseyTest. class );
        this .register(HelloService. class );
        // Access through //application.wadl
        this .register(WadlResource. class );
    }

    private  void  configureSwagger() {
        // Available at localhost:port/swagger.json
        this .register(ApiListingResource. class );
        this .register(SwaggerSerializers. class );
        BeanConfig config =  new  BeanConfig();
        config.setConfigId( "springboot-jersey-swagger-docker-example" );
        config.setTitle( "Spring Boot + Jersey + Swagger + Docker Example" );
        config.setVersion( "v1" );
        config.setContact( "wzh" );
        config.setSchemes( new  String[] {  "http" ,  "https"  });
        config.setBasePath( this .apiPath);
        config.setResourcePackage( "sample.jersey" );
        config.setPrettyPrint( true );
        config.setScan( true );
    }
}

5、Swagger配置类，支持spirngMVC RESTful文档功能

import  static  com.google.common.base.Predicates.or;
import  static  springfox.documentation.builders.PathSelectors.regex;

import  java.util.Arrays;

import  org.springframework.beans.factory.annotation.Value;
import  org.springframework.context.annotation.Bean;
import  org.springframework.context.annotation.Configuration;

import  com.google.common.base.Predicate;

import  springfox.documentation.builders.ApiInfoBuilder;
import  springfox.documentation.builders.PathSelectors;
import  springfox.documentation.builders.RequestHandlerSelectors;
import  springfox.documentation.service.ApiInfo;
import  springfox.documentation.service.ApiKey;
import  springfox.documentation.service.SecurityScheme;
import  springfox.documentation.spi.DocumentationType;
import  springfox.documentation.spring.web.plugins.Docket;
import  springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * api doc -- springfox swagger configuration
 */

@Configuration
@EnableSwagger2
public  class  SwaggerConfig {

    @Value ( "${spring.jersey.application-path}" )
    private  String apiPath;

    @Bean
    public  SecurityScheme apiKey() {
        return  new  ApiKey( "access_token" ,  "accessToken" ,  "header" );
    }

    @Bean
    public  Docket apiConfig() {
        return  new  Docket(DocumentationType.SWAGGER_2).groupName( "controller" )
                // 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
                .apiInfo(apiInfo()).select()
                // 控制暴露出去的路径下的实例
                // 如果某个接口不想暴露,可以使用以下注解
                // @ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下
                .apis(RequestHandlerSelectors.basePackage( "sample.jersey.controller" )).paths(PathSelectors.any())
                .build().useDefaultResponseMessages( false ).securitySchemes(Arrays.asList(apiKey()));
    }

    @Bean
    public  Docket restConfig() {
        return  new  Docket(DocumentationType.SWAGGER_2).groupName( "jax-rs" ).apiInfo(restInfo()).forCodeGeneration( true )
                .pathMapping( "/" ).select().paths(paths()) // 过滤的接口
                .build().useDefaultResponseMessages( false );
    }

    // 请求url匹配，支持and or，可以过滤筛选
    private  Predicate paths() {
        return  or(regex( "/test/.*" ), regex( "/rest/.*" ));  //
    }

    private  ApiInfo apiInfo() {
        return  new  ApiInfoBuilder().title( "berheley service controller api " ) // 大标题
                .description( "spring boot webservice 平台 API" ) // 小标题
                // .termsOfServiceUrl("http://ww.swagger.com/")
                // .contact(new Contact("swagger", "www.swagger.com",
                // "[email protected]"))
                .version( "2.0" ).build();
    }

    private  ApiInfo restInfo() {
        return  new  ApiInfoBuilder().title( "berheley service rest api " ) // 大标题
                .description( "spring boot webservice 平台 API" ) // 小标题
                .version( "2.0" ).build();
    }
}

6、SprintMVC风格的web 服务示例

package  sample.jersey.controller;

import  org.springframework.stereotype.Controller;
import  org.springframework.web.bind.annotation.RequestMapping;
import  org.springframework.web.bind.annotation.RequestMethod;
import  org.springframework.web.bind.annotation.RequestParam;
import  org.springframework.web.bind.annotation.ResponseBody;

import  io.swagger.annotations.ApiOperation;
import  io.swagger.annotations.ApiParam;

@Controller
@RequestMapping ( "/test" )
public  class  TestController {

    @ResponseBody
    @RequestMapping (value =  "/show" , method = RequestMethod.POST)  // 这里指定RequestMethod，如果不指定Swagger会把所有RequestMethod都输出，在实际应用中，具体指定请求类型也使接口更为严谨。
    @ApiOperation (value =  "测试接口" , notes =  "测试接口详细描述" )
    public  String show( @ApiParam (required =  true , name =  "name" , value =  "姓名" )  @RequestParam (name =  "name" ) String stuName) {
        return  "success" ;
    }
}

7、JAX-RS 实现的服务示例