首页 > 代码库 > Spring-boot 之 Swagger2（打造不一样的api）
Spring-boot 之 Swagger2（打造不一样的api）
一、Swagger2是什么？
Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
官网：http://swagger.io/
GitHub地址：https://github.com/swagger-api/swagger-ui
二、Swagger2的maven依赖
1 <dependency> 2 <groupId>io.springfox</groupId> 3 <artifactId>springfox-swagger2</artifactId> 4 <version>2.7.0</version> 5 </dependency> 6 <dependency> 7 <groupId>io.springfox</groupId> 8 <artifactId>springfox-swagger-ui</artifactId> 9 <version>2.7.0</version>10 </dependency>
三、SwaggerConfig的配置
import org.springframework.beans.factory.annotation.Value;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.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration@EnableSwagger2public class Swagger2Configuration { @Value(value = "${swagger.package}") private String swaggerPackage; @Bean public Docket buildDocket() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInf()).select() .apis(RequestHandlerSelectors.basePackage(swaggerPackage))
.select()
.paths(PathSelectors.any()).build(); } @SuppressWarnings("deprecation") private ApiInfo buildApiInfo() { return new ApiInfoBuilder() .title("随便找的个网站平台API接口说明文档") .description("百度一下：https://www.baidu.com/") .termsOfServiceUrl("https://www.baidu.com/") .version("1.0") .build(); }}
通过@Configuration注解，让Spring-boot来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2Configuration。
再通过buildDocket函数创建Docket的Bean之后，
buildApiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给Swagger2来展现。
一般采用指定扫描的包路径来定义
Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。
四、配置Controller中的API
下面的内容是基于spring-boot进行配置的，不一定适合所有框架（自己也是瞎琢磨出来的，有错的地方欢迎指出）
1.这里面有几个常用到的注解
@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了，看上去很有条理
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
header 请求参数的获取：@RequestHeader
query 请求参数的获取：@RequestParam
path（用于restful接口） 请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
@ApiModelProperty 这里顾名思义，描述一个model的属性，就是标注在被标注了@ApiModel的class的属性上，这里的value是对字段的描述，example是取值例子，注意这里的example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在api文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在model中的顺序
2.Controller中的实现
import java.util.HashMap;import java.util.List;import java.util.Map;import javax.servlet.http.HttpServletRequest;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.ResponseBody;import org.springframework.web.bind.annotation.RestController;import com.share.service.BlogService;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;@Api(value="博客相关接口")@RestController@RequestMapping("/blog")public class BlogController { @Autowired private BlogService blogService; @ResponseBody @ApiOperation(value ="查询文章列表", notes="") @RequestMapping(value = "/getBlogList",method={RequestMethod.POST,RequestMethod.GET}) @ApiImplicitParam(paramType="query", name = "type_id", value = "http://www.mamicode.com/类型ID", required = true, dataType = "String")public List<Map> getBlogList(HttpServletRequest req) { String type_id = req.getParameter("type_id");return blogService.getBlogList(type_id); };}
备注：带绿色背景的表示使用Swagger2的过程中，所用到的相关代码
这个时候打开：http://localhost:8081/apidoc/index.html，你就可以看到
这个错误的原因是$ref需要一个JSON字符串，我们的类型不符合Swagger2的要求导致报错，但如果继续往滚动，是可以看到我们定义的接口的
并且这个接口是能够请求到数据的，所以上面的错误我们可以忽略
额，但是作为有强迫症的你，怎么可能忽略，大多程序员都是眼睛进不了沙子的，更别说这么大一粒沙子！！！
下一步就解决这个问题。
五、处理 Errors: responses.200.schema.items.$ref
上一步有说过是$ref需要一个JSON字符串，我们的类型不符合Swagger2的要求导致报错。
找到原因就好办了，只要我们把结果转换成JSON字符串就好了。
1.在pom.xml里面增加一项配置
<!-- FastJson --><dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.15</version></dependency>
2.将List<Map>转为JSON
import com.alibaba.fastjson.JSON;
...
@ResponseBody@ApiOperation(value ="查询博客列表", notes="根据url的id来指定删除对象")@RequestMapping(value = "/getBlogList",method={RequestMethod.POST,RequestMethod.GET})@ApiImplicitParam(paramType="query", name = "type_id", value = "http://www.mamicode.com/类型ID", required = true, dataType = "String")public String getBlogList(HttpServletRequest req) { String type_id = req.getParameter("type_id"); List<Map> result = blogService.getBlogList(type_id); return JSON.toJSONString(result);}
备注：蓝色背景的表示新增加的内容，接下来刷新接口就发现错误没啦，问题解决了，好了，打完了！
Spring-boot 之 Swagger2（打造不一样的api）