SpringBoot2.0整合Jersey+Swagger2

一. Swagger

• 官网：https://swagger.io
• 通过集成Swagger，建立前后端交流沟通的标准化桥梁(尽管有postman)，通过swagger注解，和可视化的Swagger-ui，方便前端同学直接了当的对后端服务进行调用和参数选用

二. SpringBoot2.x条件下，Jersey集成Swagger2

• 1. 本地环境：

环境名	版本	描述
JDK	1.8
Springboot	2.2.1.RELEASE	使用初始化默认版本
Jersey	2.2.1.RELEASE	引入spring-boot-starter-jersey
Springboot	2.2.1.RELEASE	使用初始化默认版本
swagger-core	1.6.0	swagger-jersey2-jaxrs
swagger-ui	2.2.10

• 2. pom.xml文件引入jar依赖

 			 	<!-- springboot 集成 jersey 、swagger 实现 JAX-RS Restful 開始 -->
		     	<dependency>
		    	    <groupId>org.springframework.boot</groupId>
		    	    <artifactId>spring-boot-starter-jersey</artifactId>
		     	</dependency>
		     	<dependency>
		     	    <groupId>io.swagger</groupId>
		     	    <artifactId>swagger-jersey2-jaxrs</artifactId>
		     	    <version>1.6.0</version>
		    	</dependency>
		    	<!-- swagger 静态资源 -->
		    	<dependency>
		    	    <groupId>org.webjars</groupId>
		    	    <artifactId>swagger-ui</artifactId>
		    	    <version>2.2.10</version>
		    	</dependency>
		    	<!-- springboot 集成 jersey 、swagger 实现 JAX-RS Restful 結束 -->

• 3. Jersey和Swagger配置类

  JerseySwaggerConfig.java，此类同时配置了Jersey和Swagger，也可拆分为两个配置类

			 	package com.enough.jersey.demo.config;
		     	
		     	import com.alibaba.fastjson.support.jaxrs.FastJsonProvider;
		     	import com.crc.cims.bpmp.ssdp.demo.resources.RootResource;
		     	import io.swagger.jaxrs.config.BeanConfig;
		     	import io.swagger.jaxrs.listing.AcceptHeaderApiListingResource;
		     	import io.swagger.jaxrs.listing.ApiListingResource;
		     	import io.swagger.jaxrs.listing.SwaggerSerializers;
		     	import org.glassfish.jersey.server.ResourceConfig;
		    	import org.springframework.beans.factory.annotation.Value;
		    	import org.springframework.stereotype.Component;
		    	
		    	import javax.annotation.PostConstruct;
		    	
		    	/**
		    	 * @program: bpmp-ssdp-demo
		    	 * @description: Jersey+Swagger配置
		    	 * @author: lidong
		    	 * @create: 2019/12/03
		    	 */
		    	@Component
		    	public class JerseySwaggerConfig extends ResourceConfig {
		    	
		    	    @Value("${spring.jersey.application-version}")
		    	    private String api_version;
		    	
		    	    @Value("${spring.jersey.application-path}")
		    	    private String apiPath;
		    	
		    	    public JerseySwaggerConfig() {
		    	        register(RootResource.class);
		    	        // 使用FastJson作为rest接口序列化工具
		    	        register(FastJsonProvider.class);
		    	    }
		    	
		    	    @PostConstruct
		    	    private void init2() {
		    	        configureSwagger();
		    	        register(SwaggerSerializers.class);
		    	        register(ApiListingResource.class);
		    	        register(AcceptHeaderApiListingResource.class);
		    	    }
		    	
		    	    /**
		    	     * 配置Swagger
		    	     */
		    	    private void configureSwagger() {
		    	        this.register(ApiListingResource.class);
		    	        this.register(SwaggerSerializers.class);
		    	        BeanConfig config = new BeanConfig();
		    	        config.setConfigId("ssdp测试Demo服务接口文档");
		    	        config.setTitle("ssdp测试Demo服务接口文档");
		    	        config.setVersion(api_version);
		    	        config.setContact("enough");
		    	        config.setSchemes(new String[] {"http", "https"});
		    	        config.setBasePath(this.apiPath);
		    	        config.setResourcePackage("com.enough.jersey.demo.resources");
		    	        config.setPrettyPrint(true);
		    	        config.setScan(true);
		    	    }
		    	}
		    

• 4. 引入swagger-ui静态资源
  • https://github.com/swagger-api/swagger-ui/tree/master/dist
  • 下载swagger-ui/dist下的静态资源，copy到resources/static目录下
  • 修改index.html为swagger-ui.html（静态资源名理论上可随意指定，swagger-ui只是为了统一）
  • 按项目需求修改*.html里的脚本文件

			     	<script>
			     	    window.onload = function() {
			     	      // Begin Swagger UI call region
			     	      const ui = SwaggerUIBundle({
			     	           // 一般只修改url,目的为了访问获取到swagger.json的信息，用来展示
			     	        url: "http://localhost:8761/api/swagger.json",
			     	        dom_id: '#swagger-ui',
			     	        deepLinking: true,
			     	        presets: [
			    	          SwaggerUIBundle.presets.apis,
			    	          SwaggerUIStandalonePreset
			    	        ],
			    	        plugins: [
			    	          SwaggerUIBundle.plugins.DownloadUrl
			    	        ],
			    	        layout: "StandaloneLayout"
			    	      })
			    	      // End Swagger UI call region
			    	      window.ui = ui
			    	    }
			    	  </script>

• 5. REST资源层使用swagger注解
  • Jersey根资源类上必须使用 @API()注解，否则无法加载所有rest请求
  • Rest请求加上@ApiOperation和@ApiImplicitParam注解

			 	@Component
		     	@Path("/ssdp")
		     	@Api(value = "根资源")
		     	public class RootResource {
		     	
		     	    @Path("/test")
		     	    public Class<TestResource> testResourceClass(){
		     	        return TestResource.class;
		     	    }
		    	}

			 	    @POST
		     	    @Produces({MediaType.APPLICATION_JSON})
		     	    @ApiOperation(value = "提交一个新的流程单信息", notes = "参数为新建的流程单信息")
		     	    @ApiImplicitParam(name = "paramrter", value = "新建的流程单信息", required = true,                
		     	    				  dataType = "ProcessParamrter")
		     	    public ReturnResult <String> submitProcess(ProcessParamrter paramrter) {
		     	        Map <String, Object> rags = ProcessParamrter.getProcessArgsMap(paramrter);
		     	        Result result = signParser.doProcessSSDP(rags, SsdpApiMethod.TASK_EXT);
		     	        return ReturnResult.buildReturnResult(result, String.class);
		    	    }

• 6. 常用注解：

名称	描述
@Api	Resouce注解
@ApiOperation	Resource详细接口注解
@ApiModel	Model注解
@ApiModelProperty	Model Property注解
@ApiParam	请求参数注解

三. 启动项目，访问swagger地址即可

• http://localhost:8761/swagger-ui.html#/
• http://localhost:8761/api/swagger.json

参考资料

• 示例源码地址：
• [官方示例地址：](http://petstore.swagger.io%20%20Jersey2.X%20%E9%9B%86%E6%88%90Swagger-core)

• [第三方资料:](https://www.jianshu.com/p/633e936577b5)