1.swagger2的使用

在前后端分离的过程中，接口文档的重要性不言而喻，但是如何保持一个文档的最新和代码的一致性一直是一个问题，有时候定义了文档，代码中修改了一点小的东西，总会忘记同步修改文档，时间长了，自己都比较蒙，还需要看一下代码才能发现问题。

1.1 添加依赖

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

1.2 编写配置类

package cn.tina.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;

@Configuration
@EnableSwagger2
public class Swaager {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
 .groupName("第一组")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.tina"))
                .paths(PathSelectors.any())
                .build();
    }
/*@Bean//可以写多个,用于分组
public Docket createRestApi2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("第二组")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.tina"))
                .paths(PathSelectors.any())
                .build();
    }*/

private ApiInfoapiInfo() {
	return new ApiInfoBuilder()
            .title("接口文档--测试")  //接口文档的名字
            .description("这只是一个测试的接口文档")//接口文档的描述
            .termsOfServiceUrl("http://localhost:8080")  //服务条款网址
            .version("1.0.0")  //接口文档的版本
            // 接口文档维护联系信息
            .contact(new Contact("tina", "", "123456789@qq.com"))
            .build();
	}

}

1.3 启动,输入地址可查看http://localhost:8080/swagger-ui.html

1.4 Swagger注解 swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数

1.4.1 实体注解

@ApiModel()用于类；表示对类进行说明，用于参数用实体类接收 
value–表示对象名description–描述 
@ApiModelProperty()用于方法，字段；表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

1.4.2 实体示例

package cn.entity;

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

import java.io.Serializable;

@ApiModel(value = "Student", description = "学生对象Student")
public class Student implements Serializable {

@ApiModelProperty(value = "用户名", name = "username", example = "张三")
private String username;
@ApiModelProperty(value = "状态", name = "state", required = true)
private Integer state;

@ApiModelProperty(value = "id数组", hidden = true)
private String[] ids;

public String getUsername() {
return username;
    }

public void setUsername(String username) {
this.username= username;
    }

public Integer getState() {
return state;
    }

public void setState(Integer state) {
this.state= state;
    }

public String[] getIds() {
return ids;
    }

public void setIds(String[] ids) {
this.ids= ids;
    }
}

1.4.3 方法和类的注解

@Api() 用于类；表示标识这个类是swagger的资源 
tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list
@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 
@ApiImplicitParam() 用于方法 表示单独的请求参数 
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

1.4.4 编写Controller

package cn.controller;

import cn.entity.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

@Api(value = "登录请求",tags = "登录,测试")
@RestController
public class LoginController {

@ApiOperation(value="新增学生信息",notes="注意问题点")
@ApiImplicitParams({
@ApiImplicitParam(name="username",value="学生姓名",dataType="string"),
@ApiImplicitParam(name="state",value="学生状态",dataType="integer")
    })
@GetMapping("/add")
public  Student toAdd(String username,Integer state){
        Student student =new Student();
student.setState(999);
student.setUsername("张三");
return student;
    }

@ApiOperation(value="删除学生信息")
@GetMapping("/del")
public  String del(){
return "删除成功";
    }

@ApiIgnore
    @PostMapping("/del")
public  String upd(Integer id){
return "修改成功"+id;
    }
}

2. PostMain

Postman一款非常流行的API调试工具。其实，开发人员用的更多。因为测试人员做接口测试会有更多选择，例如Jmeter、soapUI等。不过，对于开发过程中去调试接口，Postman确实足够的简单方便，而且功能强大。

2.1 下载地址https://www.getpostman.com/downloads/