Swagger在php和java项目中的应用

Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

• 对于后端开发人员来说

1. 不用再手写WiKi接口拼大量的参数，避免手写错误
2. 对代码侵入性低，采用全注解的方式，开发简单
3. 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
4. 增加了开发成本，写接口还得再写一套参数配置

• 对于前端开发来说

1. 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
2. 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

• 对于测试来说

1. 对于某些没有前端界面UI的功能，可以用它来测试接口
2. 操作简单，不用了解具体代码就可以操作

Swagger在java项目中的应用

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案

步骤

1. 导入knife4j的maven坐标

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version>
</dependency>

2. 导入knife4j相关配置类（WebMvcConfig）
3. 设置静态资源，否则接口文档页面无法访问

package com.demo.config;import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.List;@Slf4j
@Configuration
@EnableSwagger2
@EnableKnife4j
public class WebMvcConfig extends WebMvcConfigurationSupport {/*** 设置静态资源映射* @param registry*/protected void addResourceHandlers (ResourceHandlerRegistry registry) {    				registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}@Beanpublic Docket createRestApi () {// 文档类型return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.demo.controller")) // swagger扫描的包.paths(PathSelectors.any()).build();}/*** 介绍接口信息*/private ApiInfo apiInfo () {return new ApiInfoBuilder().title("Robin's Swagger documents").version("1.0").description("Robin's Swagger documents").build();}
}

4. 在LoginCheckFilter中设置不需要处理的请求路径

package com.demo.filter;import com.alibaba.fastjson.JSON;
import com.demo.common.BaseContext;
import com.demo.common.R;
import com.demo.entity.Employee;
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.AntPathMatcher;import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;/*** 检查用户是否已经完成登录*/@Slf4j
@WebFilter(filterName = "loginCheckFilter", urlPatterns = "/*")
public class LoginCheckFilter implements Filter {// 路径匹配器，支持通配符public static final AntPathMatcher PATH_MATCHER = new AntPathMatcher();// 定义不需要处理的请求路径public static final String[] urls = new String[]{"/employee/login", // 登录接口"/employee/logout", // 退出接口"/backend/**", // 放行后台静态资源"/front/**", // 放行前台静态资源"/common/download", // 文件下载接口"/user/login", // 移动端登录"/user/sendMsg", // 获取验证码接口"/doc.html", // swagger文档路径"/webjars/**","/swagger-resources/**","/v2/api-docs",};@Overridepublic void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {HttpServletRequest request = (HttpServletRequest) servletRequest;HttpServletResponse response = (HttpServletResponse) servletResponse;// 1、获取本次请求的URIString requestUri = request.getRequestURI();// 2、判断本次请求是否需要处理，如果不需要处理，则直接放行if (check(requestUri)) {filterChain.doFilter(request, response);return;}// 3、判断登录状态，如果已登录，则直接放行Long empId = (Long) request.getSession().getAttribute("employee");Long userId = (Long) request.getSession().getAttribute("user");if (empId != null || userId != null) {// 将当前登录的用户id保存到ThreadLocal中if (empId != null) BaseContext.setCurrentId(empId);if (userId != null) BaseContext.setCurrentId(userId);filterChain.doFilter(request, response);return;}// 4、如果未登录，则返回未登录结果log.info("拦截到请求：{}", request.getRequestURI());response.getWriter().write(JSON.toJSONString(R.error("NOTLOGIN")));}/*** 路径匹配，检测本次请求是否需要放行* @param requestUri 本次请求资源* @return 路径匹配结果，true-放行，false-不放行*/public boolean check (String requestUri) {for (String url:urls) {if (PATH_MATCHER.match(url, requestUri)) {return true;}}return false;}
}

访问域名/doc.html，

常用注解

注解	说明
@Api	用在请求的类上，例如Controller，表示对类的说明
@ApiModel	用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty	用在属性上，描述响应类的属性
@ApiOperation	用在请求的方法上，说明方法的用途、作用
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApilmplicitParams 注解中，指定一个请示参数的各个方面

R实体类补充注解：

package com.demo.common;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;import java.io.Serializable;
import java.util.HashMap;
import java.util.Map;/*** 通用返回结果，服务端响应的数据最终都会封装成此对象* @param <T>*/
@Data
@ApiModel("返回结果")
public class R<T> implements Serializable {@ApiModelProperty("编码：1成功，0和其它数字为失败")private Integer code; //编码：1成功，0和其它数字为失败@ApiModelProperty("错误信息")private String msg; //错误信息@ApiModelProperty("数据")private T data; //数据@ApiModelProperty("动态数据")private Map map = new HashMap(); //动态数据public static <T> R<T> success(T object) {R<T> r = new R<T>();r.data = object;r.code = 1;return r;}public static <T> R<T> error(String msg) {R r = new R();r.msg = msg;r.code = 0;return r;}public R<T> add(String key, Object value) {this.map.put(key, value);return this;}}

套餐实体类补充注解：

package com.demo.entity;import com.baomidou.mybatisplus.annotation.FieldFill;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.io.Serializable;
import java.math.BigDecimal;
import java.time.LocalDateTime;/*** 套餐*/
@Data
@ApiModel("套餐")
public class Setmeal implements Serializable {private static final long serialVersionUID = 1L;@ApiModelProperty("主键")private Long id;//分类id@ApiModelProperty("分类id")private Long categoryId;//套餐名称@ApiModelProperty("套餐名称")private String name;//套餐价格@ApiModelProperty("套餐价格")private BigDecimal price;//状态 0:停用 1:启用@ApiModelProperty("状态 0:停用 1:启用")private Integer status;//编码@ApiModelProperty("编码")private String code;//描述信息@ApiModelProperty("描述信息")private String description;//图片@ApiModelProperty("图片")private String image;@TableField(fill = FieldFill.INSERT)private LocalDateTime createTime;@TableField(fill = FieldFill.INSERT_UPDATE)private LocalDateTime updateTime;@TableField(fill = FieldFill.INSERT)private Long createUser;@TableField(fill = FieldFill.INSERT_UPDATE)private Long updateUser;//是否删除@ApiModelProperty("是否删除")private Integer isDeleted;
}

套餐接口补充注解：

package com.demo.controller;import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.demo.common.R;
import com.demo.dto.SetmealDto;
import com.demo.entity.Category;
import com.demo.entity.Setmeal;
import com.demo.service.CategoryService;
import com.demo.service.SetmealDishService;
import com.demo.service.SetmealService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.BeanUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.web.bind.annotation.*;import java.util.List;
import java.util.Set;
import java.util.stream.Collectors;/*** 套餐管理*/
@Slf4j
@RestController
@RequestMapping("/setmeal")
@Api(tags = "套餐相关接口")
public class SetmealController {@Autowiredprivate SetmealService setmealService;@Autowiredprivate SetmealDishService setmealDishService;@Autowiredprivate CategoryService categoryService;/*** 新增套餐* @param setmealDto 套餐实体* @return 返回信息*/@CacheEvict(value = "setmealCache", allEntries = true)@PostMapping@ApiOperation(value = "新增套餐接口")public R<String> save(@RequestBody SetmealDto setmealDto) {setmealService.saveWithDish(setmealDto);return R.success("新增套餐成功");}/*** 套餐分页查询* @param page 页码* @param pageSize 单页数据量* @param name 套餐名称* @return 列表数据*/@GetMapping("/page")@ApiOperation(value = "套餐分页查询")@ApiImplicitParams({@ApiImplicitParam(name = "page", value = "页码", required = true),@ApiImplicitParam(name = "pageSize", value = "每页记录数", required = true),@ApiImplicitParam(name = "name", value = "套餐名称", required = false),})public R<Page<SetmealDto>> page (int page, int pageSize, String name) {// 构建分页构造器Page<Setmeal> pageInfo = new Page<>(page, pageSize);LambdaQueryWrapper<Setmeal> lambdaQueryWrapper = new LambdaQueryWrapper<>();// 添加查询条件，根据name进行模糊查询lambdaQueryWrapper.like(name != null, Setmeal::getName, name);// 添加排序条件，根据更新时间降序排列lambdaQueryWrapper.orderByAsc(Setmeal::getStatus).orderByDesc(Setmeal::getUpdateTime);setmealService.page(pageInfo, lambdaQueryWrapper);// 对象拷贝，补充分类信息Page<SetmealDto> dtoPage = new Page<>(page, pageSize);BeanUtils.copyProperties(pageInfo, dtoPage, "'records'");List<Setmeal> records = pageInfo.getRecords();List<SetmealDto> list = records.stream().map((item) -> {// 对象拷贝SetmealDto setmealDto = new SetmealDto();BeanUtils.copyProperties(item, setmealDto);// 设置分类名称Category category = categoryService.getById(item.getCategoryId());if (category != null) {setmealDto.setCategoryName(category.getName());}return setmealDto;}).collect(Collectors.toList());dtoPage.setRecords(list);return R.success(dtoPage);}/*** 批量删除套餐* @param ids 套餐id* @return 返回信息*/@CacheEvict(value = "setmealCache", allEntries = true)@DeleteMapping@ApiOperation(value = "批量删除套餐")public R<String> delete(@RequestParam List<Long> ids) {setmealService.removeWithDish(ids);return R.success("套餐数据删除成功");}/*** 批量上下架* @param ids 套餐id* @param status 上下架状态* @return 返回信息*/@PostMapping("/status/{status}")@ApiOperation(value = "批量上下架")public R<String> updateStatus(@RequestParam List<Long> ids, @PathVariable int status) {List<Setmeal> setmealList = ids.stream().map((item) -> {Setmeal setmeal = new Setmeal();setmeal.setId(item);setmeal.setStatus(status);return setmeal;}).collect(Collectors.toList());setmealService.updateBatchById(setmealList);return R.success("更新成功");}/*** 获取套餐详情数据* @param id 套餐id* @return 套餐实体信息*/@GetMapping("/{id}")@ApiOperation(value = "获取套餐详情数据")public R<SetmealDto> detail(@PathVariable Long id) {SetmealDto setmealDto = setmealService.getSetmealWithDish(id);return R.success(setmealDto);}/*** 修改套餐* @param setmealDto 套餐实体* @return 舞台信息*/@PutMapping@ApiOperation(value = "修改套餐")public R<String> update(@RequestBody SetmealDto setmealDto) {setmealService.updateWithDish(setmealDto);return R.success("编辑成功");}/*** 根据条件查询套餐数据* @param setmeal 套餐过滤条件* @return 套餐列表*/@GetMapping("/list")@Cacheable(value = "setmealCache", key="#setmeal.categoryId + '_' + #setmeal.status", unless = "#result.data.size() == 0")@ApiOperation(value = "根据条件查询套餐数据")public R<List<Setmeal>> list(Setmeal setmeal) {log.info("未命中缓存查询");LambdaQueryWrapper<Setmeal> lambdaQueryWrapper = new LambdaQueryWrapper<>();// 分类条件lambdaQueryWrapper.eq(setmeal.getCategoryId() != null, Setmeal::getCategoryId, setmeal.getCategoryId());// 上下架状态lambdaQueryWrapper.eq(setmeal.getStatus() != null, Setmeal::getStatus, setmeal.getStatus());// 排序lambdaQueryWrapper.orderByDesc(Setmeal::getUpdateTime);List<Setmeal> list = setmealService.list(lambdaQueryWrapper);return R.success(list);}
}

重新启动服务，查看实体和接口文档

Swagger在php项目中的应用

1. 安装swagger包

zircote/swagger-php是swagger的php版,是一个扩展库，可以通过composer来进行安装

composer require zircote/swagger-php

2. 安装Swagger ui

将swagger-ui下载下来以后，把dist目录下的文件复制到项目public/docs目录下, 这个目录可以自定义, 通俗来讲就是放到项目能访问到的目录下, 然后再将dist目录下的swagger-initializer.js文件中的url改成./openapi.yaml, 这里的openapi.yaml是生成文档后的文件名,意思是访问本地的openapi.yaml文件

<?php
namespace app\controller;use app\BaseController;
use think\App;
use think\facade\Request;/*** @OA\Info (*     title = "Robins's API documetns",*     version = "1.0",*     description="本文档仅限于测试"* )*/
class Index extends BaseController
{public function getDoc() {$openapi = \OpenApi\Generator::scan([__ROOT__ . '/../app']);// 生成yaml文件file_put_contents(__ROOT__ . '\doc\dist\openapi.yaml', $openapi->toYaml());}/*** @OA\Get (*     path="/",*     tags = {"用户订单列表接口"},*     summary = "用户订单列表接口",*     description = "获取用户订单信息",*     @OA\Parameter (name = "order_id", in = "query", description = "订单号", required = true),*     @OA\Parameter (name = "account_id", in = "query", description = "账户id", required = true),*     @OA\Response(response = "200",description = "The data"),*     @OA\MediaType(*          mediaType="application/json",*          @OA\Schema(ref="#/components/schemas/Info"),*     )* )* @return \think\response\Json*/public function index(){      $accountId = Request::post('account_id', 0);       $orderId = Request::post('order_id', '');       $data = Order::where(['account_id' => $accountId, 'order_id' => $orderId])->select()->toArray();return json($data);}
}

swagger在php项目中的注解还需要一点点摸索熟练