What？

官网介绍如下：

总结一下：
遵循OpenAPI规范、最流行、最强大的API工具，贯穿整个API开发的生命周期包括（ 设计、文档输出、测试、部署）

Why？

通过集成Swagger，建立前后端交流的标准化桥梁，允许生产、显示、消费对应的API服务

How？

依赖：

• • 版本使用约束

  swagger-core	jdk	maven
  1.X	1.7	3.0.4+
  2.X	1.8	3.0.4+

集成：

由于需要改造的工程环境为Spring 3.2.6 、Jersey 2.24 、jdk1.7 ，故本文引用的是Swagger1.X，并通过Servlet配置的方式实现集成。

集成swagger-core

• 添加maven依赖：

<!-- swagger-core -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId>
    <version>1.5.17</version>
</dependency>

• Jersey Servlet配置（web.xml）

<!-- Jersey REST -->
<servlet>
  <servlet-name>Jersey REST Service</servlet-name>
  <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
      <param-name>jersey.config.server.provider.packages</param-name>
      <param-value>
      <!-- Swagger -->
      io.swagger.jaxrs.listing,
      <!-- 此处填写个人的包路径-->
      com.youcompany.package
      </param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

• Swagger Config配置

import io.swagger.annotations.Contact;
import io.swagger.annotations.Info;
import io.swagger.annotations.SwaggerDefinition;
import javax.ws.rs.ext.Provider;

@Provider
@SwaggerDefinition(info = @Info(description = "描述", version = "版本号", title = "标题", contact = @Contact(name = "联系人姓名", email = "联系人邮箱")), schemes = {
        SwaggerDefinition.Scheme.HTTP }, basePath = "基准路径")
public interface SwaggerConfig {
}

• 常用注解配置

• 示例代码：
  Resource层：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import java.util.Date;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import 

@Component
@Path("/info")
@Api(value = "基本信息接口")
public class InfoResource {

    @GET
    @Path("/{name}")
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes(MediaType.APPLICATION_JSON)
    @ApiOperation(value = "根据姓名查询基本信息", response = InfoDTO.class)
    public InfoDTO findByName(@ApiParam(value = "姓名") @PathParam(value = "name") String name) {
        return new InfoDTO(name, new Date(), "130XXXXXXXXX");
    }
}

Model层

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.Date;

@ApiModel(description = "基本信息DTO")
public class InfoDTO {

    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "出生日期")
    private Date birthDay;
    @ApiModelProperty(value = "手机号")
    private String mobileNum;

    public InfoDTO(String name, Date birthDay, String mobileNum) {
        this.name = name;
        this.birthDay = birthDay;
        this.mobileNum = mobileNum;
    }
}

集成swagger-ui

• 屏幕快照 2017-12-06 下午2.08.52.png

• 将其解压到Jersey工程的src/main/webapp 目录下，如图：

  
  屏幕快照 2017-12-06 下午2.16.38.png

• 修正index.html中的如下代码

// Build a system
const ui = SwaggerUIBundle({
url: "swaggerDemo/swagger.json",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui

至此即完成了 swagger-ui 的集成

官网示例：

• 示例地址：

参考内容：