What？

官网介绍如下：

THE WORLD'S MOST POPULAR API TOOLING
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
https://swagger.io

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

Why？

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

How？

依赖：

• Swagger-core

  • 版本使用约束

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

• Swagger UI

集成：

由于需要改造的工程环境为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 {
}

• 常用注解配置

注解详细API

• 示例代码：
  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 org.springframework.stereotype.Component;

@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;
    }
}

运行工程，假设rootPath为 http://localhost:8080/swaggerDemo，
则通过访问
http://localhost:8080/swaggerDemo/swagger.json
或者
http://localhost:8080/swaggerDemo/swagger.yaml
若访问成功，即证明集成swagger-core 成功

集成swagger-ui

• 下载swagger-ui/dist 目录下的文件，如图：
  

  屏幕快照 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 的集成

官网示例：

• 示例地址： http://petstore.swagger.io

参考内容：

Jersey2.X 集成Swagger-core