前后端分离，Swagger框架

前后端分离，Swagger框架

1.简介
随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架，而且swagger可以完全模拟http请求，入参出参和实际情况差别几乎为零。
　　没有API文档工具之前，大家都是手写API文档的（维护起来相当困难），在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏。但是能称之为“框架”的，估计也只有swagger了
2.搭建项目
基于SpringBoot的
1.pom.xml

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

2.配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .enable(true)
            .apiInfo(apiInfo())
            .select() //返回ApiSelectorBuilder
            .apis(RequestHandlerSelectors.basePackage("com.ls.controller"))
            .paths(PathSelectors.any()) //只给product路径产生API文档
            .build();
    }
    //文档基础信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            // 文档标题
            .title("swagger")
            // 文档描述
            .description("user接口文档")
            .termsOfServiceUrl("http://localhost:8080")
            .version("v1.0")
            .build();
    }
}

3.Controller

@RestController
@RequestMapping("/user")
@Api(value = "用户接口",tags = {"user"})
public class UserController {

    @ApiOperation(value="分页条件查询用户列表")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "userName",value = "用户姓名",required = false,paramType = "query",dataType = "string"),
        @ApiImplicitParam(name = "email",value = "用户邮箱",required = false,paramType = "query",dataType = "string"),
        @ApiImplicitParam(name = "status",value = "状态",required = false,paramType = "query",dataType = "integer"),
        @ApiImplicitParam(name = "pageNum",value= "当前页数", required = true,paramType = "query",dataType = "integer"),
        @ApiImplicitParam(name = "pageSize",value= "每页显示数量", required = true,paramType = "query",dataType = "integer")
    })
    @GetMapping("/query")
    public List<User>  query(@ApiIgnore User user,Integer pageNum, Integer pageSize){
        System.out.println(user);

        System.out.println(pageNum);
        System.out.println(pageSize);
        return null;
    }
    @GetMapping("/add")
    @ApiOperation("新增用户")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "userName",value = "用户姓名",required = false,paramType = "query",dataType = "string"),
        @ApiImplicitParam(name = "email",value = "用户邮箱",required = false,paramType = "query",dataType = "string"),
        @ApiImplicitParam(name = "password",value = "用户密码",required = false,paramType = "query",dataType = "string"),

    })
    public Boolean add(@ApiIgnore User user){
        System.out.println(user);
        return true;
    }

    @GetMapping("/delete")
    @ApiOperation("删除用户")
    public Boolean delete(@ApiParam(value = "用户id",required = true) @RequestParam Integer userId ){
        System.out.println(userId);
        return true;
    }

}

4.User类

@Data
public class User {
    private Integer userId;
    private String userName;
    private String password;
    private  Integer status;
    private String email;
    private Date createTime;
    private Date modifyTime;


}

5.访问：http://localhost:8080/swagger-ui.html

swagger注解说明

注解	作用	说明
@Api	用在请求的类上，表示对类的说明	tags="说明该类的作用，可以在UI界面上看到的注解， value="该参数没什么意义，在UI界面上也看到，所以不需要配置”
@ApiOperation	用在请求的方法上，说明方法的用途、作用	value=“说明方法的用途、作用”，notes=“方法的备注说明”
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面	name：参数名, value：参数的汉字说明、解释, required：参数是否必须传;paramType：参数放在哪个地方· header --> 请求参数的获取：@RequestHeader, query --> 请求参数的获取：@RequestParam, · path（用于restful接口）–> 请求参数的获取：@PathVariable,· body（不常用）, · form（不常用) ;dataType：参数类型，默认String，其它值dataType=“Integer” ; defaultValue：参数的默认值
@ApiResponses	用在请求的方法上，表示一组响应	@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400,message：信息，例如"请求参数没填好"response：抛出异常的类
@ApiModel	用于响应类上，表示一个返回响应数据的信息	（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）,@ApiModelProperty：用在属性上，描述响应类的属性
@ApiIgnore()	用于类，方法，方法参数	表示这个方法或者类被忽略