【Swagger-UI】配置Swagger-UI生成在线API文档

【Swagger-UI】配置Swagger-UI生成在线API文档

方案/适用/归类：API在线文档调试

Swagger-UI官网

使用Swagger的有什么好处？

1.Swagger号称世界上最流行的API框架
2.Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
3.直接运行，在线测试API

（1）先来看一下Swagger有哪些常用注解及说明

@Api(value = "接口类模块名",tags = {"接口模块标签名称"}) 作用在模块类上
@ApiOperation("接口说明") 作用在接口方法上
@ApiModel("POJO说明") 作用在模型类上：如VO、BO
@ApiModelProperty(value = "属性说明",hidden = true) 作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("参数说明") 作用在参数、方法和字段上，类似@ApiModelProperty

（2）添加Swagger-UI有关依赖

  <!--Swagger-UI 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>

（3）配置Swagger-UI

package com.daqi.config;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
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;

/**
 * @author 東方神劍
 * 時間 2023/04/25下午 02:56
 */

@Configuration       //标识配置类
@EnableSwagger2      //开启Swagger2的自动配置
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.daqi.reggie.controller"))
                //为有@Api注解的Controller生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("天使外卖接口文档")
                .description("本文档为【天使外卖接口文档】后端api接口规范。")
                .contact(new Contact("东方神剑", "http://localhost:8081/swagger-ui", "2144290349@qq.com"))
                .version("1.0")
                .build();
    }
}

（4）使用Swagger–添加有关注解到controller模块中

以实战项目的 EmployeeController接口为例：

package com.daqi.reggie.controller;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.itheima.reggie.common.R;
import com.itheima.reggie.entity.Employee;
import com.itheima.reggie.service.EmployeeService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.util.DigestUtils;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;

/**
 * @author 東方神劍
 * 時間 2023/04/03上午 09:48
 */
@Api(value = "EmployeeController",tags = {"员工管理"})
@Slf4j
@RestController
@RequestMapping("/employee")
public class EmployeeController {

    @Autowired(required=false)
    private EmployeeService employeeService; 

    @ApiOperation("员工登录")
    @PostMapping("/login")
    public R<Employee> login(HttpServletRequest request,@RequestBody Employee employee){
        //1.密码MD5加密处理
        String password = employee.getPassword();
        password = DigestUtils.md5DigestAsHex(password.getBytes());

        //2.根据用户页面提交的用户名username查询数据库
        LambdaQueryWrapper<Employee> queryWrapper = new LambdaQueryWrapper<>();
        queryWrapper.eq(Employee::getUsername, employee.getUsername()); //构造查询条件
        Employee emp = employeeService.getOne(queryWrapper); //查询数据库
        //3.查询不到返回失败结果
        if(emp == null){
            return  R.error("登入失败！");
        }
        //4.密码比对
        if(!emp.getPassword().equals(password)){   //!!!
            return  R.error("登入失败！");
        }
        //5.查看员工账号状态是否禁用
        if(emp.getStatus() == 0){
            return  R.error("账号已禁用！");
        }
        //6.登录成功，将员工ID存入Session返回
        request.getSession().setAttribute("employee", emp.getId());
        return R.success(emp);
    }

    @ApiOperation("员工退出")
    @PostMapping("/logout")
    public R<String> logout(HttpServletRequest request){
        request.getSession().removeAttribute("employee");
        return R.success("退出成功！");
    }

    @ApiOperation("新增员工")
    @PostMapping
    public R<String> save(HttpServletRequest request,@RequestBody Employee employee){
        //设置初始密码123456，需要进行md5加密处理
        employee.setPassword(DigestUtils.md5DigestAsHex("123456".getBytes()));

        employeeService.save(employee); 
        return R.success("添加用户成功！");
    }

    @ApiOperation("员工信息分页查询")
    @GetMapping("/page")
    public R<Page> page(int page,int pageSize,String name){
        Page pageInfo = new Page(page,pageSize);
        LambdaQueryWrapper<Employee> queryWrapper = new LambdaQueryWrapper();

        //添加过滤条件  // 先判断是否为空，再进行比较  // LambdaQueryWrapper构造器添加泛型避免报错
        queryWrapper.like(StringUtils.isNotEmpty(name), Employee::getName,name);

        //添加排序条件  // 根据 updateTime 来排序
        queryWrapper.orderByDesc(Employee::getUpdateTime);

        //执行查询
        employeeService.page(pageInfo,queryWrapper);

        return R.success(pageInfo);
    }
    
    @ApiOperation("根据id修改员工信息")
    @PutMapping
    public R<String> update(HttpServletRequest request,@RequestBody Employee employee){
        Long id = Thread.currentThread().getId();
        employeeService.updateById(employee);
        
        return R.success("员工信息修改成功！");
    }

    @ApiOperation("根据id查询员工信息")
    @GetMapping("/{id}")
    public R<Employee> getById(@PathVariable long id){
        log.info("根据id查询员工信息......");
        Employee employee = employeeService.getById(id);
        
        if(employee != null){
            return R.success(employee);
        }
        return R.error("没有查询到员工信息......");
    }
}

（5）使用Swagger–添加有关注解到entity实体类中

package com.itheima.reggie.entity;

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

import javax.persistence.*;

/**
 * @author 東方神劍
 * 時間 2023/04/25下午 05:24
 */
@ApiModel("用户实体")
@Data
@Table(name = "tb_user")
public class TbUser {
        @Id
        @GeneratedValue(strategy = GenerationType.IDENTITY)
        @ApiModelProperty("用户id")
        private Integer userId;

        @ApiModelProperty("用户名")
        private String username;

        @ApiModelProperty("密码")
        private String password;

        @ApiModelProperty("邮箱")
        private String email;

        @ApiModelProperty("电话")
        private String phone;

        @ApiModelProperty("状态")
        private Integer status;

        @ApiModelProperty("角色id")
        private Integer roleId;

        @Transient
        private Role role;
}

（6）运行项目查看接口文档

访问：http://localhost:8081/项目名/swagger-ui.html
访问成功，OK！