Spring-boot 之 Swagger2（打造不一样的api）

Posted 2020-09-23 add+

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

 

将接口页面使用到的静态网页放到 /static/xxx 目录下即可

静态页面下载路径：

链接：https://share.weiyun.com/f36464f5c9f3979753ab126b71a96f8d

（密码：btkr）

 

同时还需要在：application.properties文件里面指向对应的controller层

swagger.package=com.share.controller

 

三、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
@EnableSwagger2
public class Swagger2Configuration {

    @Value(value = "${swagger.package}")
    private String swaggerPackage;
    
    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo()).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 = "类型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 = "类型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);
} 

备注：蓝色背景的表示新增加的内容，接下来刷新接口就发现错误没啦，问题解决了，好了，打完了！