简介
问题：在我们API开发中，服务端和客户端会约定接口文档，而在实际开发中则可能出现，接口文档延迟更新，造成客户端看到的接口和服务端实际开发的接口不一致的问题；
Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 接口名、接口参数 等 API 信息。
你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
swagger的一些常用工具
1. swagger文件编写工具 (swagger editor)：在线版本的swagger编辑器：http://editor.swagger.io/，支持json，yaml两种格式
如果想了解swagger文档的编写语法，可以在http://swagger.io/docs/specification/swagger-extensions/这里查看
2. swagger ui可视化文件生成工具 (swagger ui)：静态页面（用于将json，yaml转化为可视化的页面显示）
3. Swagger-codegen (swagger codegen)：用于生成客户端和服务端各个语言的代码
4. swagger hub接口管理 (swagger hub) ：swagger文档云端管理工具，类似于github
swagger api 集成
目前官网上有提供 Jersey 1.X Jersey 2.X RESTEasy 2.X Mule的配置方法，官网wiki写的很详细https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X#hooking-up-swagger-core-in-your-application
对于各个不同的rest服务，git-hub也有提供相关的demo，https://github.com/swagger-api/swagger-samples
配置样例（jersey2）
配置API项目过程中的样例，主要有两种配置方式：web.xml的servlet配置、BeanConfig配置。
1. 引入swagger相关jar包
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey2-jaxrs</artifactId>
<version>1.5.10</version>
</dependency>
2. web.xml中jersey配置中加入对，swagger相关resource的路径
<servlet>
<servlet-name>JerseyServlet</servlet-name>
<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>jersey.config.server.provider.packages</param-name>
<param-value>
io.swagger.jaxrs.listing,<!--swagger相关资源-->
com.sohu.tv.api4.rest.controller <!--业务资源>
</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>JerseyServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
3. swagger相关配置（一些全局描述）
web.xml中servlet配置（第一种方式）
<servlet>
<servlet-name>Jersey2Config</servlet-name>
<servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
<init-param>
<param-name>api.version</param-name>
<param-value>1.0.0</param-value>
</init-param>
<init-param>
<param-name>swagger.api.basepath</param-name>
<param-value>/</param-value>
</init-param>
<init-param>
<!-- 是否扫描全部资源，包含没使用swagger注解声明过的rest资源 -->
<param-name>scan.all.resources</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
此外还有：
swagger.api.host 、 swagger.api.schemes、swagger.api.title、
swagger.filter都可以在servlet的参数中声明
BeanConfig配置（第二种方式）
<!–web.xml中声自定义明配置的servlet-->
<servlet>
<servlet-name>Bootstrap</servlet-name>
<servlet-class>com.sohu.tv.api4.utils.Bootstrap</servlet-class>
<init-param>
<param-name>scan.all.resources</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
// 自定义servlet的类配置
public class Bootstrap extends HttpServlet {
@Override
public void init(ServletConfig config) throws ServletException {
super.init(config);
BeanConfig beanConfig = new BeanConfig();
beanConfig.setVersion("1.0.2");
beanConfig.setSchemes(new String[]{"http"});
beanConfig.setHost("localhost:8002");
beanConfig.setBasePath("/api");
// resourcepackage指明需要扫描的业务rest资源路径（未指明，则不会扫描资源）
beanConfig.setResourcePackage("io.swagger.resources");
// setScan说明beanconfig是否生效被扫描
beanConfig.setScan(true);
// 如果想让未加swagger注解的rest资源被扫到，需加如下配置：
ReaderConfigUtils.initReaderConfig(config);
}
}
完成上述配置，既可以在项目中，使用swagger注解完成接口描述。