Swagger

介绍

swagger一般是后台开发人员使用的一种自动生成接口文档的一种技术。

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务1。 它支持API自动生成同步的在线文档，这意味着使用Swagger后可以直接通过代码生成文档，不再需要自己手动编写接口文档了。这对程序员来说非常方便，可以节约写文档的时间去学习新技术。

Swagger的主要优点包括：
自动化文档生成：通过分析代码中的注释和特定注解，Swagger可以自动生成API文档，减少人工编写文档的工作量。
可视化API设计：Swagger提供了可视化的API设计界面，使得设计和管理API变得更加直观和方便。
API探索与测试：开发人员可以通过Swagger界面直接对API进行测试，查看请求和响应示例，简化开发和调试过程。
规范和标准：Swagger遵循OpenAPI规范，这是一个广泛接受的API描述标准，有助于提高API的互操作性和可重用性。

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
<dependency>
        <groupld>com.github.xiaoymin</groupld>

       <artifactld>knife4j-spring-boot-starter</artifactld>           

      <version>3.0.2</version>
</dependency>

使用方式

操作步骤:
1、导入knife4j的maven坐标
2、导入knife4j相关配置类

创建一个配置类（项目都有配置类）在配置类里面加入相关注解

@EnableSwagger2

@EnableKnife4j

 @Bean
    public Docket createRestApi() {
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxx.xxxx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

注释：这段代码是自动扫描项目中的controller层生成接口文档

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("xxxx")
                .version("1.0")
                .description("xxxx接口文档")
                .build();
    }

注释:这个方法是为了封装上边的方法，描述一下接口文档，给接口文档设置一些标题，版本号，等内容。

3、设置静态资源，否则接口文档页面无法访问
  /**
     * 设置静态资源映射
     * @param registry
     */
    @Override
 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
      log.info("开始进行静态资源映射...");
    registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
 

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

LoginCheckFilter这个类是设置项目登陆时不用拦截的路径。

下面是LoginCheckFilter的源码。仅供参考。

@Slf4j
@WebFilter(filterName = "loginCheckFFilter",urlPatterns = "/*")
public class LoginCheckFFilter 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;
        //获取本次请求的URL
        String requestURI = request.getRequestURI();
        log.info("拦截到请求：{}",requestURI);
        //定义不需要处理的路径
        String [] urls = new String[]{"/employee/login","/employee/logout","/backend/**","/front/**","/common/**","/user/sendMsg","/user/login","/doc.html","/webjars/**","/swagger-resources","/v2/api-docs"};
        //判断本次请求是否需要处理
        boolean check=check(requestURI,urls);
        //如果不需要处理就直接放行
        if (check){
            log.info("本次请求{}不需要处理",requestURI);
            filterChain.doFilter(request,response);
            return;
        }
        //判断登陆状态，如果已登录则放行
        if (request.getSession().getAttribute("employee")!=null){
            log.info("用户已登录，id为{}",request.getSession().getAttribute("employee"));
           Long empId=(Long) request.getSession().getAttribute("employee");
            BaseContext.setCurrentId(empId);
            filterChain.doFilter(request,response);
            return;
        }
        if (request.getSession().getAttribute("user")!=null){
            log.info("用户已登录，id为{}",request.getSession().getAttribute("user"));
            Long userId=(Long) request.getSession().getAttribute("user");
            BaseContext.setCurrentId(userId);
            filterChain.doFilter(request,response);
            return;
        }
        //如果未登录则返回未登录结果
        log.info("用户未登录");
        response.getWriter().write(JSON.toJSONString(R.error("NOTLOGIN")));
        return;
    }

    /**
     * 判断路径是否需要放行
     * @param requestURI
     * @param urls
     * @return
     */
    public boolean check(String requestURI,String[] urls){
        for (String url : urls) {
            boolean match = PATH_MATCHER.match(url, requestURI);
            if (match){
                return true;
            }
        }
        return false;
    }
}

设置完成后启动项目，在浏览器上输入localhost:8080/doc.html就可以看到接口文档了。

常用注解

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

这些注解就是给接口文档一些更加详细的描述。使用更加方便。