SpringBoot Swagger2整合

Swagger简介 

Swagger是一款Restful接口的文档在线自动生成+功能测试的软件。

 

Swagger是一个规范和完整的框架。用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统

作为服务器以同样的速度 来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。  

SpringBoot整合Swagger2

SpringBoot整合Swagger2只需要以下几个步骤：

Step1.导入依赖：                                                                                                  

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

Step2.新建一个Swagger的配置类

package com.reset.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by chendai on 2018/3/21.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
//                   当前包路径
                   .apis(RequestHandlerSelectors.basePackage("com.reset.controller"))
                    .paths(PathSelectors.any()).build();

    }
//构建api文档的详细信息函数
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //页面标题
                    .title("springBoot测试使用Swagger2构建RESTful API")
                //创建人
                    .contact(new Contact("chendai","http://www.baidu.com",""))
                 //版本号
                    .version("1.0")
                //描述
                    .description("API 描述")
                    .build();
    }
}

Step3.使用Swagger2进行测试：

  使用Swagger2进行测试的类我们选择在controller层：

package com.reset.controller;

import com.reset.model.RestMessgae;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

/**
 * Created by chendai on 2018/3/19.
 */
@RestController
@Api("swaggerTestController相关api")
public class TestController {

    /**
     * Restful Get请求测试
     */
    @ApiOperation(value = "根据id查询学生的信息",notes = "查询数据库中某个学生的信息")
    @ApiImplicitParam(name ="id",value = "学生id",paramType = "path",required = true,dataType = "String")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",dataType = "String",paramType = "query",example = "1112")
    })
    @ApiResponses({
            @ApiResponse(code=400,message = "请求参数没有填好"),
            @ApiResponse(code=404,message="请求路径没有找到")
    })
    @GetMapping(value = "testRest/{id}")
    public RestMessgae testGetResetful(@PathVariable String id){
       RestMessgae restMessgae = new RestMessgae();
        System.out.println(id);
        return restMessgae;
    }
    
}

打开浏览器访问“ http://localhost:8080/swagger-ui.html”会看到如下的界面

在输入框中输入id的值后点击”Try it out“按钮，我们可以查看到下面的结果：

这样测试结果就非常的明显了。

Swagger2注解说明

@Api()：作用于类上，表示这个类是swagger的资源。

    tags = ”说明该类的作用“

@ApiOperation()：用在请求的方法上，说明的方法的用户和作用

    value=“说明方法的用途、作用”

    notes="方法的备注说明“

@ApiImplicitParams()：用在请求的方法上，表示一组参数说明，可以包含多个 @ApiImplicitParam()

@ApiImplicitParam()：指定一个请求参数的各个方面

       name：参数名

       value：参数的汉字说明

       required：参数是否必须传

       dataType：参数类型

       defaultValue：参数的默认值

@ApiResponses()：用在请求的方法上，表示一组响应。可以包含多个 @ApiResponse()

@ApiResponse()：用于表示一个错误的响应信息

    code：数字

    message：信息

    response：抛出异常的类      

@ApiModel()：用在响应类上，表示一个返回响应数据的信息。

@ApiModelProperty()：用在属性上，描述响应类的属性

@ApiModel() 和  @ApiModelProperty() 使用示例如下：

package com.reset.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * Created by chendai on 2018/3/21.
 */
@ApiModel(description = "返回响应数据")
public class RestMessgae {

    @ApiModelProperty(value = "错误信息")
    private String message;
    @ApiModelProperty(value = "状态码")
    private String code;
    @ApiModelProperty(value = "返回的数据")
    private Object data;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public Object getData() {
        return data;
    }

    public void setData(Object data) {
        this.data = data;
    }
}