Rest的API解决方案(jersey与swagger集成)

一、项目目标
动静分离的架构，即客户端和服务器端的分离，客户端可以是IOS、android或者静态的页面。需要服务器端提供webservice服务，并且为了方便编写api接口文档，所以引入了swagger。

二、技术选型
为什么使用jersey而不用spring mvc
虽然spring-web提供了REST的功能，但是没有实现JAX-RS的标准。

二、maven配置

<properties>
	<jetty.version>8.1.16.v20140903</jetty.version>
	<jersey.version>2.9</jersey.version>
	<spring.version>4.0.1.RELEASE</spring.version>
</properties>

<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-jersey2-jaxrs</artifactId
	<version>1.5.9</version>
	<exclusions>
		<exclusion>
			<groupId>javax.ws.rs</groupId>
			<artifactId>jsr311-api</artifactId>
		</exclusion>
	</exclusions>
</dependency>

<dependency>
	<groupId>org.glassfish.jersey.containers</groupId>
	<artifactId>jersey-container-servlet</artifactId>
	<version>${jersey.version}</version>
</dependency>
<dependency>
	<groupId>org.glassfish.jersey.media</groupId>
	<artifactId>jersey-media-json-jackson</artifactId>
	<version>${jersey.version}</version>
</dependency>
<!-- jersey-spring -->
<dependency>
	<groupId>org.glassfish.jersey.ext</groupId>
	<artifactId>jersey-spring3</artifactId>
	<version>${jersey.version}</version>
	<exclusions>
		<exclusion>
			<groupId>org.springframework</groupId>
			<artifactId>spring-beans</artifactId>
		</exclusion>
		<exclusion>
			<groupId>org.springframework</groupId>
			<artifactId>spring-core</artifactId>
		</exclusion>
		<exclusion>
			<groupId>org.springframework</groupId>
			<artifactId>spring-web</artifactId>
		</exclusion>
	</exclusions>
</dependency>
还需要引入spring的包，作者使用的是4.0.1.RELEASE

三、swagger的操作
3.1swagger ui 准备
下载地址:https://github.com/swagger-api/swagger-ui
swagger其实就是一套静态页面，自定义了一套api的json格式，通过解析json将api展现出来。
下载之后将静态页面放在webapp目录下即可，还需要改一下index.html中的url地址，改成本地的api接口地址即可。

3.2注册
注册swagger，即将swagger的rest服务注册到jersey中。
register(io.swagger.jaxrs.listing.ApiListingResource.class);
register(io.swagger.jaxrs.listing.AcceptHeaderApiListingResource.class);
register(io.swagger.jaxrs.listing.SwaggerSerializers.class);

四、swagger集成过程中遇到的坑
4.1 jackson中报类型找不到，class java.lang.String
解决方法：更新jackson包

<dependency>
	<groupId>com.fasterxml.jackson.jaxrs</groupId>
	<artifactId>jackson-jaxrs-json-provider</artifactId>
	<version>2.7.4</version>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.jaxrs</groupId>
	<artifactId>jackson-jaxrs-base</artifactId>
	<version>2.7.4</version>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.core</groupId>
	<artifactId>jackson-annotations</artifactId>
	<version>2.7.4</version>
</dependency>
<dependency>
	<groupId>com.fasterxml.jackson.datatype</groupId>
	<artifactId>jackson-datatype-joda</artifactId>
	<version>2.7.4</version>
</dependency>

4.2 swagger-ui.js中报的错误
4.2.1 operation is null, 大概在2338行

operation = path[method];
[b]if (operation === null) continue;[/b]
var sharedParameters = path.parameters || [];
var parameters = operation.parameters || [];
for (i in sharedParameters) {
  var parameter = sharedParameters[i];
  parameters.unshift(parameter);
}
if(method !== 'parameters' && _.isObject(operation)) {
  operation.parameters = operation.parameters || parameters;
}

4.2.2 enumValues is null, 大概在4383行

if ([b]enumValues != null &&[/b] typeof enumValues !== 'undefined') {
  var id;
  param.allowableValues = {};
  param.allowableValues.values = [];
  param.allowableValues.descriptiveValues = [];
  for (id = 0; id < enumValues.length; id++) {
    var value = enumValues[id];
    var isDefault = (value === param.default || value+'' === param.default);
    param.allowableValues.values.push(value);
    // Always have string for descriptive values....
    param.allowableValues.descriptiveValues.push({value : value+'', isDefault: isDefault});
  }

最终结果

评论

1 楼 wlg841344127 2017-03-24  

楼主  我一直报错 Can't read swagger JSON from http://localhost:8081/api/api-docs