SpringBoot系列：Spring Boot集成Swagger2

Swagger2

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

随着前后端分离越来越流行，但同时前后端开发的成本也增加了，撰写和维护接口文档会耗费开发人员很大一部分精力，而Swagger的出现恰好解决了这个问题，极大的提升了团队开发的沟通效率，同时也方便开发人员进行接口开发自测。

Spring Boot集成Swagger2

首先在我们的项目，引入Swagger2依赖。

        <!-- swagger2API文档支持 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!-- swagger2API文档支持 -->

 

然后进行对应的配置，Swagger2默认使用配置类，这也是Spring Boot的便捷之处。

@Configuration声明为配置类，@EnableSwagger2则开启Swagger2文档支持，其余大致为固定写法，只是具体属性有所不同。basePackage指明文档包含的包范围（主要配置点），title和description即为文档标题和描述，contact为创建人信息，version是版本信息。

 

配置好之后，其实就已经生效，对于之前的接口，其实已经可以生成文档了，只是少了一些描述信息。

新建SwaggerApi，呃……这就是一个普通的Controller，只不过在方法上添加了Swagger2的文档描述。

 

其中@ApiOperation是接口的描述信息，@ApiImplicitParam针对具体的参数添加描述，@ApiImplicitParams则是多个@ApiImplicitParam，更多注解使用，可以参考官方文档。需要注意的是，使用@PathVariable需要设置paramType="path"，而使用@RequestParam时，需要设置paramType="query"，不然可能会导致好好的接口无法接受到请求参数。

然后我们启动项目，输入http://localhost:10900/swagger-ui.html，也即项目访问路径 + /swagger-ui.html。

 

可以看到项目中的Controller均以展示出来，尤其是我们的SwaggerApi，我们可以看到之前编写的描述信息，至于怎么使用，相信到这里已经不用我多说了。

 

添加请求参数，然后抱着试一试的心态Try it out，就可以看到接口返回结果了。

 

源码地址：https://github.com/imyanger/springboot-project/tree/master/p3-springboot-swagger2