Swagger简单了解

Swagger

• 介绍

  使用swagger你只需要按照它的规范去定义接口及接口相关信息，在通过swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。

  官网：https://swagger.io/

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

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

• 使用方式

  操作步骤：

  1. 导入knife4j的maven坐标

  2. 导入knife4j相关配置类
     

  3. 设置静态资源，否则接口文档页面无法访问

     registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
     registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
             
     

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

     @WebFilter(filterName = "LoginCheckFilter",urlPatterns = "/*")//利用过滤器拦截，拦截所有的请求  urlPatterns = "/*"
     @Slf4j
     public class LoginCheckFilter implements Filter {
         //路径匹配器，并支持通配符
         public static final AntPathMatcher PATH_MATCHER = new AntPathMatcher();
     
         @Override
         public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
             HttpServletRequest request = (HttpServletRequest)servletRequest;
             HttpServletResponse response = (HttpServletResponse)servletResponse;
     
     
             //1. 获取本次请求的URI
             String requestURI = request.getRequestURI();
             //如果请求路径为"/backend/index.html"会与放行的"/backend/**"路径匹配不上，会导致无法识别，这时需要路径匹配器
             log.info("拦截到的请求：{}",requestURI);
     
             //1.2 定义不需要处理的请求路径，比如：登录页面，退出，静态资源，主要是拦截controller资源
             String[] urls = new String[]{
                     "/employee/login",
                     "/employee/logout",
                     "/backend/**",
                     "/front/**",
                     "/common/**",
                     "/user/sendMsg",//移动端发送短信
                     "/user/login",//移动端登录
                     "/doc.html",
                     "/webjars/**",
                     "/swagger-resources",
                     "/v2/api-docs"
             };
             //2. 判断本次请求是否需要处理，封装一个方法类进行比较
             boolean check = check(urls, requestURI);
             //3. 如果不需要处理，则直接放行
             if (check) {
                 log.info("本次请求{}不需要处理",requestURI);
                 filterChain.doFilter(request,response);//放行
                 return;
             }
             //   4-1. 判断登录状态，如果已登录，则直接放行  后台系统
             if(request.getSession().getAttribute("employee")!=null){
                 log.info("用户已登录，用户id为：{}",request.getSession().getAttribute("employee"));
     
                 Long employeeId =(Long) request.getSession().getAttribute("employee");
                 BaseContext.setCurrentId(employeeId);//保存用户id，用于公共字段自动填充使用
     
                 long id = Thread.currentThread().getId();
                 log.info("线程id为：{}",id);
                 //已经登录，直接放行
                 filterChain.doFilter(request,response);//放行
                 return;
             }
     
             //   4-2. 判断登录状态，如果已登录，则直接放行  移动端判断
             if(request.getSession().getAttribute("user")!=null){
                 log.info("用户已登录，用户id为：{}",request.getSession().getAttribute("user"));
     
                 Long userId =(Long) request.getSession().getAttribute("user");
                 BaseContext.setCurrentId(userId);//保存用户id，用于公共字段自动填充使用
     
                 long id = Thread.currentThread().getId();
                 log.info("线程id为：{}",id);
                 //已经登录，直接放行
                 filterChain.doFilter(request,response);//放行
                 return;
             }
             //5. 如果未登录则返回未登录结果，通过输出流的方式向客户端响应数据
             log.info("用户未登录");
             response.getWriter().write(JSON.toJSONString(R.error("NOTLOGIN")));
     
             return;
         }
         /*
         * 路径匹配,检查本次请求是否需要放行
         * */
         public boolean check(String[]urls,String requestURI){
             for (String url : urls) {
                 boolean match = PATH_MATCHER.match(url, requestURI);
                 if (match) {
                     return true;
                 }
             }
             return false;
         }
     }
     
     

     

     swagger首页

  

  swagger接口调试
  

  5. 常用注解

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