二十六、spring-boot结合Swagger2构建RESTful API测试体系

     spring-boot结合Swagger2构建RESTful API测试体系

一、pom.xml配置文件

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.yang</groupId>
    <artifactId>dubbo_springBoot</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>dubbo_springBoot</name>
    <description>Demo project for Spring Boot</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.0.BUILD-SNAPSHOT</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>


        <!-- 用来融合Swagger2实现restful api文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
        </dependency>

    </dependencies>



    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

    <repositories>
        <repository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

    <pluginRepositories>
        <pluginRepository>
            <id>spring-snapshots</id>
            <name>Spring Snapshots</name>
            <url>https://repo.spring.io/snapshot</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
        <pluginRepository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>


</project>

二、配置类

package com.yang;

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;

/**
 * 在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，
 * 对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、
 * 通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。
 * 完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html
 *
 */
@Configuration//声明Spring的配置类
@EnableSwagger2//注解来启用Swagger2
public class Swagger2 {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yang"))//扫描的包名
                .paths(PathSelectors.any())
                .build();
    }


    //返回API文档信息类：主页面展示的内容
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("结合swagger使用，实现restful api文档")//标题
                .description("欢迎大家，基于java语言的构建中小型互联网公司后台架构")//描述
                .termsOfServiceUrl("http://blog.csdn.net/huohuangfengcheng/article/details/77326490")
                .version("1.0")//版本
                .build();
    }
}

三、API接口类

package com.yang.web;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.yang.domain.User;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;





@RestController
@RequestMapping(value="/users")
public class UserController {


       static Map<Integer, User> Users = Collections.synchronizedMap(new HashMap<Integer, User>()); 


        @ApiOperation(value="获取用户列表")//描述这个方法的作用
        @RequestMapping(value="/getUserList",method=RequestMethod.GET)
        public List<User> getUserList(){
            List<User> User=new ArrayList<User>(Users.values());
            return User;
        }


        //被 @ModelAttribute 注解的方法会在Controller每个方法执行之前都执行
        @ApiOperation(value="创建用户")
        @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
        @RequestMapping(value="/addUsers",method=RequestMethod.POST)
        public String addUsers(@ModelAttribute User User){
            //此方法会先从model去获取key为"user"的对象,如果获取不到会通过反射实例化一个User对象
            Users.put(User.getId(), User);
            return Users.size()+"";
        }



        @ApiOperation(value="根据id获取用户信息")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer",paramType="path")
        @RequestMapping(value="/getUser/{id}",method=RequestMethod.GET)
        public User getUser(@PathVariable Integer id){
            return Users.get(id);
        }

         @ApiOperation(value="根据id更新用户信息")
         @ApiImplicitParams({
           @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer",paramType="path"),
           @ApiImplicitParam(name = "user", value = "用户实体", required = true, dataType = "User")
          })
        @RequestMapping(value="/updateUser/{id}", method=RequestMethod.PUT) 
        public String updateUser(@PathVariable Integer id, @ModelAttribute User s) { 
            User User = Users.get(id); 
            User.setName(s.getName()); 
            User.setAge(s.getAge()); 
            Users.put(id, User); 
            return "success"; 
        } 


        @ApiOperation(value="根据id删除用户信息")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer",paramType="path")
        @RequestMapping(value="/deleteUser/{id}", method=RequestMethod.DELETE) 
        public String deleteUser(@PathVariable Integer id) { 
            Users.remove(id); 
            return "success"; 
        } 
}