个人备案能做什么网站,软文优化,温州网站建设公司电话,wordpress需要多大数据库Swagger在php和java项目中的应用 Swagger简介Swagger在java项目中的应用步骤常用注解 Swagger在php项目中的应用 Swagger简介
Swagger 是一个规范和完整的框架#xff0c;用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以… Swagger在php和java项目中的应用 Swagger简介Swagger在java项目中的应用步骤常用注解 Swagger在php项目中的应用 Swagger简介
Swagger 是一个规范和完整的框架用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
对于后端开发人员来说
不用再手写WiKi接口拼大量的参数避免手写错误对代码侵入性低采用全注解的方式开发简单方法参数名修改、增加、减少参数都可以直接生效不用手动维护增加了开发成本写接口还得再写一套参数配置
对于前端开发来说
后端只需要定义好接口会自动生成文档接口功能、参数一目了然联调方便如果出问题直接测试接口实时检查参数和返回值,就可以快速定位是前端还是后端的问题
对于测试来说
对于某些没有前端界面UI的功能可以用它来测试接口操作简单不用了解具体代码就可以操作
Swagger在java项目中的应用
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案
步骤
导入knife4j的maven坐标
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.2/version
/dependency导入knife4j相关配置类WebMvcConfig设置静态资源否则接口文档页面无法访问
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(Robins Swagger documents).version(1.0).description(Robins Swagger documents).build();}
}
在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 RT 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 RT success(T object) {RT r new RT();r.data object;r.code 1;return r;}public static T RT error(String msg) {R r new R();r.msg msg;r.code 0;return r;}public RT 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;//分类idApiModelProperty(分类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)PostMappingApiOperation(value 新增套餐接口)public RString 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 RPageSetmealDto page (int page, int pageSize, String name) {// 构建分页构造器PageSetmeal pageInfo new Page(page, pageSize);LambdaQueryWrapperSetmeal lambdaQueryWrapper new LambdaQueryWrapper();// 添加查询条件根据name进行模糊查询lambdaQueryWrapper.like(name ! null, Setmeal::getName, name);// 添加排序条件根据更新时间降序排列lambdaQueryWrapper.orderByAsc(Setmeal::getStatus).orderByDesc(Setmeal::getUpdateTime);setmealService.page(pageInfo, lambdaQueryWrapper);// 对象拷贝补充分类信息PageSetmealDto dtoPage new Page(page, pageSize);BeanUtils.copyProperties(pageInfo, dtoPage, records);ListSetmeal records pageInfo.getRecords();ListSetmealDto 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)DeleteMappingApiOperation(value 批量删除套餐)public RString delete(RequestParam ListLong ids) {setmealService.removeWithDish(ids);return R.success(套餐数据删除成功);}/*** 批量上下架* param ids 套餐id* param status 上下架状态* return 返回信息*/PostMapping(/status/{status})ApiOperation(value 批量上下架)public RString updateStatus(RequestParam ListLong ids, PathVariable int status) {ListSetmeal 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 RSetmealDto detail(PathVariable Long id) {SetmealDto setmealDto setmealService.getSetmealWithDish(id);return R.success(setmealDto);}/*** 修改套餐* param setmealDto 套餐实体* return 舞台信息*/PutMappingApiOperation(value 修改套餐)public RString 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 RListSetmeal list(Setmeal setmeal) {log.info(未命中缓存查询);LambdaQueryWrapperSetmeal 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);ListSetmeal list setmealService.list(lambdaQueryWrapper);return R.success(list);}
}
重新启动服务查看实体和接口文档 Swagger在php项目中的应用
安装swagger包
zircote/swagger-php是swagger的php版,是一个扩展库可以通过composer来进行安装
composer require zircote/swagger-php安装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 Robinss 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(* mediaTypeapplication/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项目中的注解还需要一点点摸索熟练
