springboot中swagger的应用总结

背景：

           近年，公司项目基本上都是采用的前后端分离的方式。前后端的联系，除了开发人员的直接沟通，更需要一个可靠、高效的API文档，经过探索，选择了使用swagger。特此总结一下用法，遇到的问题，用红色标注出来。

---

目录

背景：

1、swagger简介

2、依赖引入

3、基本配置

4、常用注解

5、例子

---

---

1、swagger简介

        Swagger：根据后台代码注解可以在线自动生成接口文档，并允许API始终与代码保持同步。

        springboot整合为例，启动服务后，访问http://ip:port/swagger-ui.html，就可以在线访问接口文档了，

        还可以直接在在线文档中进行接口测试。

        Swagger是一组开源项目，其中主要要项目如下：

        1.   Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

        2.   Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

        3.   Swagger-js: 用于JavaScript的Swagger实现。

        4.   Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

        5.   Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

        6.   Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

2、依赖引入

       需要引入两个依赖

<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>

3、基本配置

        需要用到两个方法，

         一个是配置扫描路径，扫描该包路径下所有@Controller或者@RestController的类；再根据具体的API注解生成文档，注意，只有带 @**Mapping 注解的方法才会生成接口文档，且即使没有@ApiOperation、@ApiImplicitParams也会根据方法名生成。当然，我们使用这两个注解，生成的文档才会有详细的说明。

        另一个方法则是配置文档首页的一些展示内容；

package com.cqnd