zoukankan      html  css  js  c++  java
  • Swagger2 之 Spring-boot(打造不一样的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>

    将接口页面使用到的静态网页放到 /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函数创建DocketBean之后,

    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); }

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

  • 相关阅读:
    Educational Codeforces Round 85 D. Minimum Euler Cycle(模拟/数学/图)
    Educational Codeforces Round 85 C. Circle of Monsters(贪心)
    NOIP 2017 提高组 DAY1 T1小凯的疑惑(二元一次不定方程)
    Educational Codeforces Round 85 B. Middle Class(排序/贪心/水题)
    Educational Codeforces Round 85 A. Level Statistics(水题)
    IOS中的三大事件
    用Quartz 2D画小黄人
    strong、weak、copy、assign 在命名属性时候怎么用
    用代码生成UINavigationController 与UITabBarController相结合的简单QQ框架(部分)
    Attempting to badge the application icon but haven't received permission from the user to badge the application错误解决办法
  • 原文地址:https://www.cnblogs.com/mabylove/p/7044783.html
Copyright © 2011-2022 走看看