swagger构建restful文档

偶然间发现swagger的存在，瞬间感觉比postman方便简单多了。。。（当然有各自优势）

分享以下使用swagger进行单元测试的一些心得啦

what？

     swagger restful api，用来构成restful api文档的一种格式ui,用户定义服务接口

目的：

     代码结构清晰、合标准、易于理解、扩展方便


步骤：

1 引入相关jar


   
dependency>
      groupId>io.springfoxgroupId>
      artifactId>springfox-swagger2artifactId>
      version>2.2.2version>
   dependency>

   dependency>
      groupId>io.springfoxgroupId>
      artifactId>springfox-swagger-uiartifactId>
   version>2.2.2version>
   dependency>
   dependency>
      groupId>org.springframework.bootgroupId>
      artifactId>spring-boot-starter-tomcatartifactId>

dependency>

(我集成的是springboot)

2 添加swagger 的配置类

package com.example.config;

import org.springframework.context.annotation.Configuration;
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;
import springfox.documentation.builders.ApiInfoBuilder;
/**
* Swagger2配置类
* Created by lujia on 2017/7/12.
*/
@Configuration
@EnableSwagger2
public class Swagger2 {

    public Docket createTrstApi(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("demo"))  //只有在demo包下的才会生成swagger文档
.paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注：http://blog.didispace.com/")
                .termsOfServiceUrl("http://blog.didispace.com/")
                .contact("程序猿DD")
                .version("1.0")
                .build();
    }

}




3 在你的Controller中需要暴露的接口添加如下配置



@ApiOperation(value = "获取用户列表")  //文档描述
@RequestMapping(value = {""},method = RequestMethod.GET)
  public List getuserlist(){
List list=new ArrayList(users.values());
  return  list;
  }
  @ApiOperation(value="创建用户", notes="根据User对象创建用户")
  @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
  @RequestMapping(value="", method=RequestMethod.POST)
  public String postUser(@RequestBody User user) {
    users.put(user.getId(),user);
      return "success";
  }
  @ApiOperation(value = "获取用户详细信息" ,notes = "根据url的id获取用户详细信息")
  @ApiParam(required = true,name = "id" ,value = "用户id")  //属性描述
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
  public  User getUser(@PathVariable Long id){
    return  users.get(id);
  }

  4 在你Controller中需要暴露接口的地方添加如下配置

 

static Mapusers = Collections.synchronizedMap(new HashMap());


@ApiOperation(value = "获取用户列表")  //文档描述
@RequestMapping(value = {""},method = RequestMethod.GET)
   public List getuserlist(){
  List list=new ArrayList(users.values());
   return  list;
   }
   @ApiOperation(value="创建用户", notes="根据User对象创建用户")
   @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
   @RequestMapping(value="", method=RequestMethod.POST)
   public String postUser(@RequestBody User user) {
     users.put(user.getId(),user);
       return "success";
   }
   @ApiOperation(value = "获取用户详细信息" ,notes = "根据url的id获取用户详细信息")
   @ApiParam(required = true,name = "id" ,value = "用户id")  //属性描述
@RequestMapping(value = "/{id}",method = RequestMethod.GET)
   public  User getUser(@PathVariable Long id){
     return  users.get(id);
   }

@ApiOperation和@ApiParam：都是暴露出来文档的一些表述


其他表述知道MVC的应该都能知道是什么吧，就不多做解释了


5 准备工作都差不多的时候可以测试以下效果了


访问swagge的ui界面


http://127.0.0.1:1013/swagger-ui.html/

可看到如下效果图
[img]http://dl2.iteye.com/upload/attachment/0126/1899/8e0f5778-fd69-35c7-8f71-524532d16cca.png" alt="[/img]


user-controller是我们的controller， 下面是我们之前暴露的接口后面也有我们给的文档注释

那么怎么进行单元测试呢？

一、创建用户，右键右边的model，左边的框框里就出现相关信息，在把你要添加的信息输入到对应的属性
① 模块名称(EN)
② 业务名称(CN)
③ 业务名称(EN)
④ 输出路径(File)

    填写完之后在点击try it out!
[img]http://dl2.iteye.com/upload/attachment/0126/1901/140ce75d-02c2-35bd-a752-72a28e672f81.png" alt="[/img]
       try  it out  后


[img]http://dl2.iteye.com/upload/attachment/0126/1903/4eb571d3-3946-3593-a21d-9884562e28dc.png" alt="[/img]
可看到返回的结果，如Response code返回的是200 说明ok

二、 测试刚加的数据是否真的增加进去，测试方法获取用户


[img]http://dl2.iteye.com/upload/attachment/0126/1905/e9ba399f-9d69-3762-814c-af0579a3ff9b.png" alt="[/img]


可以看到返回的就是刚刚增加的数据


简单的测试就结束啦