word无法启动转换器mswrd632-SpringBoot项目集成Swagger2，让你的接口管理轻而易举

前言：

开发完成的单元测试你会想到用什么工具？

在最之前的时候，需要起来页面或则用js的$.ajax进行测试，慢慢有了http工具，有了postman，但是自测完还要跟前端写接口规范，比如出参入参之类的字段属性以及类型等，未免有点麻烦。对于写惯了后台代码的程序员，让你写接口规范是不是很郁闷呢？

还好现在有了swagger，它可以说是全球最大的开源API规范（OAS）API开发工具框架，支持从设计文档到测试，到部署的整个API生命周期的开发。另外它是提供Restful风格的API，让使用者对接口一目了然。

---

正文：

直接上代码：

1. 引入pom依赖

io.springfox springfox-swagger2 2.8.0 io.springfox springfox-swagger-ui 2.8.0

说明：

如果你是springboot项目只需要添加以上两个依赖就好了，但是你要是spring项目，那就需要额外加上pom依赖：

com.fasterxml.jackson.core jackson-databind 2.8.12. 编写config类

SwaggerConfig.java完整代码如下：

package com.bj.hydra.config; import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * Created by @IT讲坛 on 2018/11/2. */@Configuration@EnableSwagger2public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //swagger要扫描的包路径 .apis(RequestHandlerSelectors.basePackage("com.bj.hydra.controller")) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数,注意这里的注解引用的是哪个 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("Spring Boot 测试使用 Swagger2 构建RESTful API") .contact(new Contact("@IT讲坛", "https://mp.toutiao.com", "")) //版本号 .version("1.0") //描述 .description("swaggerAPI测试") .build(); }}3. 编写controller层代码

HydraFileController.java完整代码如下：

package com.bj.hydra.controller;import com.bj.hydra.service.HydraFileService;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import lombok.extern.slf4j.Slf4j;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.*; /** * @package: com.bj.hydra.controller * @description: hydrafile控制层 * @author: @IT讲坛 * @create: 2018-11-14 17:46 **/@Slf4j@RestController@RequestMapping("/struct")@Api(tags = {"附件操作相关接口"})public class HydraFileController { @Autowired private HydraFileService hydraFileService; @ApiOperation("根据token获取大结构") @RequestMapping(value = "/structs", method = RequestMethod.POST) StrutsDTO struts(@RequestParam("token") String token) { return hydraFileService.struts(token); }}

说明：

这里的@APi里面的就是将来展示给用户的接口说明信息。

4. 起项目测试结果

启动springboot项目后，在浏览器输入地址访问：

url:

http://localhost:8088/hydra/swagger-ui.html

回车看页面如下：

看具体的根据token获取大结构方法：

测试如下：

看着以上的调试方式是不是很方便，比postman方便多了吧~，这个也是直接调到后台的，支持断点调试。

补充：

Swagger常用注解：

@Api：标识这个类是swagger的资源@ApiModelProperty：添加和操作模型属性的数据@AuthorizationScope：描述OAuth2授权范围 @ApiOperation：描述针对特定路径的操作或HTTP方法@ApiImplicitParam：表示API操作中的单个参数@ApiParam：操作参数添加额外的元数据@ApiImplicitParams：允许多个ApiImplicitParam对象列表的包装器@ApiModel：提供关于Swagger模型的额外信息@ResponseHeader：作为响应的一部分提供的标头@Authorization：声明要在资源或操作上使用的授权方案@ApiResponse：描述一个操作的可能响应@ApiResponses：允许多个ApiResponse对象列表的包装器

针对接口文档的管理还可以使用阿里的RAP管理工具，如下如所示：

RAP

这里说下swagger和rap的优缺点：

Swagger优势：

1.编写代码的过程中通过注解的方式编写接口文档

2.项目启动后直接可以访问，不需要单独部署

3.Swagger是开源框架，支持codegen，editor，ui等，使用者可以定制化开发。

缺点：

不支持Mock调用，需要其他mock插件支持

RAP优点：

1.支持Mock调用

2.支持json或者xml直接导入

缺点：

1.需要单独部署在tomcat容器中

2.不能自动生成文档，需要手动录入接口文档，接口变化时需要单独去维护RAP文档。

---

有关swagger这只是最简单的介绍，同学们还可以通过工具自动生成生成@Api注释的，我这前期是自己手动加上的，自动生成某个字段对应的注释说明，会提现到实体类entity里面。这里不过多阐述，希望有兴趣的同学多多研究。

关注➕私信回复(学习)获取最新技术干货，每天都有更新。