Spring Boot 整合 Swagger

一、为什么要用 Swagger

现在的开发模式，一般都是前后端分离的，开发接口文档就显得尤为重要，前端人员需要按照后端的功能文档调用对应的接口。在没有使用 API 文档之前，很多公司都是在纸或者 MarkDown 上写文档，不仅效率低，在进行前后端交互的时候也很容易出问题。

Swagger 是一款 API 构建工具，用于满足开发人员构建 API 的需求。Swagger 使用交互式的 API 文档来改善开发人员的体验，并提供无开销的测试功能，还支持可视化的 UI 文档界面。通过 UI 文档界面，前端人员可以很清楚的知道每个接口对应的功能，后端开发人员也可以进行相应的代码测试。

二、Spring Boot 整合 Swagger

在 SpringBoot 中整合 Swagger 很简单，只需要添加对应的依赖、然后配置相关的 Bean 即可，然后使用合适的注解用于文档说明，下面我们就来这么做。

在 pom.xml 中引入对应的依赖

        <!-- 引入 swagger 对应的依赖 --><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>

Swagger 配置类 SwaggerConfiguration

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.jas")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("swagger构建api文档").description("swaggerTest").version("1.0").build();}
}

测试的 Controller

    @ResponseBody@GetMapping("/test")@ApiOperation(value = "swagger 测试", httpMethod = "GET", response = String.class)public String testSwagger(String userName) {return "Hello " + userName;}

三、访问 UI 页面文档

输入 http://{ip地址}:{端口号}/{资源路径，如果有配置}/swagger-ui.html 即可访问到 Swagger 文档页面，如下

后端开发人员可以在 API 文档上进行测试，方便问题的排查，前端人员也可以很清晰的知道每个接口对应的功能，然后就可以放心的开发啦。

四、常用的文档注解与属性

@ApiProperty：用对象接收参数时，说明属性信息

@ApiParam：描述某个参数

@Api：用于标注在 Controller 上

description：Controller 描述信息

@ApiOperation ：对 Controller 中的资源进行定义

value：说明信息
httpMethod：HTTP 请求的方式
response：返回值类型