2021-11-19 Swagger 介绍及使用 常用注解

1. 服务器分布式部署：负载均衡：将对集群的并发请求按需分配到不同的服务器节点上
2. 基于redis实现分布式锁,redis集群
3. 数据库分布式部署，数据库负载均衡服务器，mycat，ElasticSearch搜索优化
4. 微服务架构，将原来在一个应用开发的多个模块进行拆分，单独开发和部署。
5. 高可用以及高性能。（不把鸡蛋放一个篮子里）
6. 单体架构：页面和控制之间可以进行跳转，同步请求控制器，流程控制由控制来完成
7. 前后端分离架构：前端和后端分离开发和部署，前端只能通过异步向后端发送请求，后端只负责接收请求已经参数，处理请求，返回处理结果，但是后端不负责流程控制，流程控制前端完成

接口：就是控制器中可以接受用户请求的某个方法

API 就是软件系统不同组成部分衔接的约定！！！

接口规范文档：作为一个后端开发者，我们不仅要完成接口程序的开发，还要编写接口的说明文档

Swagger工具

前后端分离开发，后端需要编写接口说明文档，会耗费比较多的时间

swagger是一个用于生成服务器接口的规范性文档的接口工具，并且能够对接口进行测试的工具

• 生成接口说明文档
• 对接口进行测试

整合：

添加依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
 

在API子工程创建一个java类，swagger配置类（java的配置方式）

package com.qfedu.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;
import sun.misc.Version;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
/*帮助我们生成接口文档
* 1.配置文档信息
* 2.配置生成规则
* 3.
* */
/*封装接口文档信息*/
    @Bean
public Docket getDocket(){
        //创建封面信息对象
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        apiInfoBuilder.title("<<西鱼商城>>后端接口说明")
                .description("此文档详细说明了西鱼商城项目后端接口规范 ")
                .version("v 2. 0.1")
                .contact(new Contact("斌哥","https://blog.youkuaiyun.com/weixin_48400115","qq.com"));

        ApiInfo apiInfo = apiInfoBuilder.build();

        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)//指定生成的文档中的封面信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.qfedu.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
}
}

启动服务 http://localhost:8080/swagger-ui.html   

 

 Swagger注解说明

swagger提供了一套注解，可以对控制器进行功能说明

@Api 类注解，在控制器类添加此注解，可以对控制器进行功能说明

@ApiOperation方法注解：说明接口方法的作用

@ApiImplicitParams 和 @ApiImplicitParam 方法注解，说明方法接口的参数

@ApiModel 和 @ApiModelProperty 当接口参数返回值为对象类型时，在实体类中添加注解说明

 案例演示：

package com.qfedu.controller;

import com.qfedu.fmmall.dao.UserDao;
import com.qfedu.fmmall.entity.User;
import com.qfedu.fmmall.service.UserService;
import com.qfedu.fmmall.vo.ResultVO;
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.*;

import javax.annotation.Resource;

@RestController
@RequestMapping("/user")
@Api(value = "用户管理",tags = "用户管理")
public class UserController {
    @Resource
    private UserService userService;
    @ApiOperation(value = "用户登录接口")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name="username",value = "用户账号",required = true),
            @ApiImplicitParam(dataType = "string",name="password",value = "用户密码",required = false,defaultValue = "1111"),
    })
    @GetMapping("/login")
    public ResultVO login(@RequestParam("username") String name,
                          @RequestParam(value = "password",defaultValue = "1111") String pwd){
        return userService.cheakLogin(name, pwd);
    }
    @ApiOperation(value = "用户注册接口")
    //@ApiImplicitParam(name="用户信息",required = true) user已经加了注解说明
    @PostMapping("/regist")
    public ResultVO regist(User user){
        System.out.println("注册成功");
        return new ResultVO(10000,"success",null);
    }
}



//实体类
package com.qfedu.fmmall.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户信息",description = "买家数据")
public class User {
    @ApiModelProperty(dataType = "int",required = false)
    private int userId;
    @ApiModelProperty(dataType = "String ",required = true,value = "注册账号")
    private String userName;
    @ApiModelProperty(dataType = "String ",required = true,value = "注册密码")
    private String userPwd;
    @ApiModelProperty(dataType = "String ",required = true,value = "注册姓名")
    private String userRealname;
    @ApiModelProperty(dataType = "String ",required = true,value = "用户头像url")
    private String userImg;

}

效果图：