与Swagger集成的三种方式

背景

　　客户在使用REST接口来获取数据，比如要根据group的名字来获取group的所有信息。假如是一个这样的REST API：/groups/groupname。但是用户的groupname中包含slash(“/”)，URL就变成/groups/groupname/groupname这样的形式。我们知道，多了一个slash之后，REST就会认为这是另外的资源，所以对于用户的请求，是没有对应的资源返回给用户的（后台是没有对应的方法接收请求）。对于这个问题的解决思路和多种解决办法，在这篇文章中不会详述，我只是说我采用的办法。增加一个新的API：/groups/**，这个新的API可以接收用户请求中包含slash这种情况。

　　因为项目中的所有RESTAPI都使用SwaggerUI展示了出来，当我增加了这个新的API之后，它也出现在了SwaggerUI上面，而我不想把这个API暴露给用户，我该怎么办呢？

　　上网查了很多资料，发现一些解决办法，比如在注解中将hidden设置为true，或者在什么pathSelector中配置你不想显示的url……当我在项目中试的时候，发现解决办法中的注解来自不同的包；即便项目中有相同的注解，我的项目中该注解却没有hidden属性（版本问题）；或者是要修改的配置类中的方法在我项目中根本就没有。Make me confused！怎么和swagger相关的有这么多不同的包。所以针对我在查询过程遇到的几种包查了查区别，终于对他们的关系和各自的实现方式有了个清晰的看法。

• difference between springfox and com.mangofactory
• ways of integrating swagger and spring

导读

　　本篇文章分为三个部分，第一部分介绍我理解的Swagger UI；第二部分由不同的包引出与Swagger UI集成的不同方式。第三部分给出实践性的Demo，放在下一篇文章里叙述。

什么是Swagger

• Swagger是将你写的接口文档化的工具。
• Swagger UI能将项目的接口以UI的形式展现出来，并可以在此UI上查看各个接口的定义，并可以直接使用此接口访问数据。Swagger UI是Swagger的一部分。

（以上是用自己的话理解的，更准确的解释请看下图）

与Swagger集成三种方式

Here is an explanation of the different libraries.

Springfox is in a sense v2 of the swagger library that used to be packaged as mangofactory. What happened was we transitioned from using a private repo to creating a github organization so support development as a team.
(Springfox是swagger库的v2版本，之前都打包成mangofactory。把库升级为spingfox是为了将原有的私有库转变成github组织以支持团队开发。)

In short mangofactory evolved into springfox which supports 2.0 version of swagger spec (in addition to 1.2). To be clear springfox and its predecessor supports spring mvc.
（mangofactory发展成了springfox，从而支持swagger的2.0规范（1.2除外），springfox和mangofactory都支持springmvc。）

io.swagger is the mother ship if you will. It has great support for spring and jax-rs. So if you’re looking for support for Jax-rs based services using spring or otherwise that’s a great option.
（io.swagger主要来支持spring和jax-rs，jax-rs是J2EE对RESTful API的支持，比如你项目中使用了spring，jax-rs，没用springmvc，可以使用这个包与swagger集成。）

参考：https://stackoverflow.com/questions/35835081/spring-swagger-ui-what-is-difference-between-io-swagger-io-springfox-and-com

总结

　　如果你的项目使用jax-rs来实现RESTful接口，你就用io.swagger来集成swagger；如果你的项目使用springmvc来实现RESTful接口，最新的方法还是推荐使用springfox，但是也存在还在继续使用mangofactory来实现与swagger集成的项目。

　　下面的链接给出了不同方式的大体实现方式，大家可以参考一下，并相应的去github上找一些demo来了解具体实现。
　　
　　https://stackoverflow.com/questions/26720090/a-simple-way-to-implement-swagger-in-a-spring-mvc-application