swagger简介

swagger是一个工具，用于自动生成web网站对外提供的服务接口文档，并且以web页面的形式进行展示。

那么我们为什么需要这个工具呢？这首先需要从web相关项目的开发模式说起。

web相关的项目，可以分为服务端的开发和客户的开发。客户端的形式一般有html页面，android，和其他一些形式。服务端提供webservice形式的接口，供客户端进行调用。

当服务端的开发和客户端的开发是由不同的团队完成的时候，需要两个团队首先约定好接口的定义。接口的定义一般是由开发服务端的团队来进行，把服务端提供的接口写成文档，交给客户端的开发人员，让他们按照文档中接口的定义，来调用服务端的服务程序。

问题在于，服务端提供的接口并不能一次完成，它是在开发过程中不断修改的。那么这就需要服务端的开发人员，在每次修改完接口之后，就要更新一次接口文档，然后把新版的文档发给客户端的开发人员，让他们按照新版的文档进行使用。

如果这个中间的过程存在滞后，特别是服务端和客户端的开发团队在两个城市的时候，那么就特别容易带来接口不匹配的问题。

swagger工具，就是为了解决这个问题而开发的。它本身是一些jar包，使用的时候需要把这些jar包加到服务端程序的编译路径里。服务接口的开发跟之前一样，需要增加的内容是，在每个需要对外提供服务的接口的上面加上一些注解，形如@param等，加上这些注解之后，swagger工具就能自动都把这些接口提取出来，并以网站的形式对外展现。

除了能够展现接口的定义之外，swagger工具还提供了对接口的单元测试功能，这个功能能够帮助客户端开发人员对接口的理解和使用。

使用swagger工具之后，对于服务端的开发人员来讲，就不需要再写接口文档了，他们只需要在对外服务接口上加上一些注解，就可以把这些接口展现给客户端的开发人员。接口定义修改了的时候，只需要同步维护这些注解，客户端人员看到的接口就会同步更新。因为维护这些注解是在代码级的，服务端的开发人员在修改代码的时候可以同步进行修改，几乎不耗费额外的精力。

而对于客户端的开发人员来讲，调用接口的时候，他们不需要再去查看接口文档了，而是直接查看由swagger工具提供的接口网站。这里提供的接口定义，比文档里面的更加准确，直接，更新及时。

总而言之，在web网站开发需要多团队协作的时候使用swagger工具，能够有效降低不同团队之间有关的接口定义的沟通成本，提高团队的开发效率。