Swagger 接口文档 | knife4j 增强方案

简介: Swagger 接口文档 | knife4j 增强方案

1.简介

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

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

在前后端分离时代一个项目的制作通过两个团队共同完成

【后端团队】后端控制层、服务层、数据访问层

【前端团队】前端控制层,视图层

前后端通过API交互,两端相对独立且松耦合

由此产生的问题是,前端人员和后端人员无法做到"即时协商、尽早解决",前后端集成联调时,最终
导致问题集中爆发。

解决方案首先指定schema【计划的提纲】,实时更新最新API,降低集成的风险。

早些年通过指定word计划文档

前后端分离后,前端测试后端解耦通过postman软件工具。后端提供解耦,需要实时更新最新的消息及改动

接着出现的解决方案就是swagger

优势:

支持 API 自动生成同步的在线文档:使用 Swagger
后可以直接通过代码生成文档,不再需要自己手动编写接口文档了,对程序员来说非常方便,可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API:光有文档还不够,Swagger
生成的文档还支持在线测试。参数和格式都定好了,直接在界面上输入参数对应的值即可在线测试接口。

2.部署

1.导入maven依赖

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

2.配置config

1.需要添加@EnableSwagger2,@EnableKnife4j两个注解

2.配置doc.html和/webjars/**资源映射

3.创建createRestApi方法和apiInfo方法

如下 :

@Slf4j
@Configuration
@EnableSwagger2
@EnableKnife4j
public class WebMvcConfig extends WebMvcConfigurationSupport {

    /**
     * 设置静态资源映射
     * @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/");

        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
    }

    /**
     * 扩展mvc框架的消息转换器
     * @param converters
     */
    @Override
    protected void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        log.info("扩展消息转换器...");
        //创建消息转换器对象
        MappingJackson2HttpMessageConverter messageConverter = new MappingJackson2HttpMessageConverter();
        //设置对象转换器,底层使用Jackson将Java对象转为json
        messageConverter.setObjectMapper(new JacksonObjectMapper());
        //将上面的消息转换器对象追加到mvc框架的转换器集合中
        converters.add(0,messageConverter);
    }

    @Bean
    public Docket createRestApi() {
        // 文档类型
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
               //com.itheima.railway.controller表示自己项目controller文件夹路径
.apis(RequestHandlerSelectors.basePackage("com.itheima.railway.controller"))
                .paths(PathSelectors.any())
                .build();
    }

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

3.在过滤器中设置不需要处理的路径

放行如下路径:

"/doc.html",
"/webjars/**",
"/swagger-resources",
"/v2/api-docs"

示例:

/**
 * 检查用户是否已经完成登录
 */
@WebFilter(filterName = "loginCheckFilter",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

        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"
        };

        //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 empId = (Long) request.getSession().getAttribute("employee");
            BaseContext.setCurrentId(empId);

            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);

            filterChain.doFilter(request,response);
            return;
        }

        log.info("用户未登录");
        //5、如果未登录则返回未登录结果,通过输出流方式向客户端页面响应数据
        response.getWriter().write(JSON.toJSONString(R.error("NOTLOGIN")));
        return;

    }

    /**
     * 路径匹配,检查本次请求是否需要放行
     * @param urls
     * @param requestURI
     * @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;
    }
}

4.测试

输入网址:http://localhost:8080/doc.html

成功~~

目录
相关文章
|
7月前
|
Java Spring
Spring Boot3整合knife4j(swagger3)
Spring Boot3整合knife4j(swagger3)
1390 1
|
2月前
|
前端开发 Java 程序员
springboot 学习十五:Spring Boot 优雅的集成Swagger2、Knife4j
这篇文章是关于如何在Spring Boot项目中集成Swagger2和Knife4j来生成和美化API接口文档的详细教程。
143 1
|
2月前
|
前端开发 Java API
Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版
本文提供了一份详细的Swagger接口文档生成工具的使用教程,包括了导入依赖、配置类设置、资源映射、拦截器配置、Swagger注解使用、生成接口文档、在线调试页面访问以及如何设置全局参数(如token),旨在帮助Java开发者快速上手Swagger。
504 0
Swagger接口文档 —— 手把手教学,全方位超详细小白能看懂,百分百能用Java版
|
2月前
|
安全 Java API
SpringSecurity结合knife4j实现swagger文档
通过将Spring Security与Knife4j相结合,我们不仅能够为RESTful API提供强大的安全防护,还能保证API文档的易用性和可访问性,这对于API的设计、开发和维护来说至关重要。这种集成方式不仅提升了开发效率,也优化了API使用者的体验,是现代API驱动开发中不可或缺的一环。
87 0
|
5月前
|
JSON 缓存 Java
Spring Boot集成 Swagger2 展现在线接口文档
本节课详细分析了 Swagger 的优点,以及 Spring Boot 如何集成 Swagger2,包括配置,相关注解的讲解,涉及到了实体类和接口类,以及如何使用。最后通过页面测试,体验了 Swagger 的强大之处,基本上是每个项目组中必备的工具之一,所以要掌握该工具的使用,也不难。
支付系统---微信支付14----创建案例项目---介绍,第二步引入Swagger,接口文档和测试页面生成工具,定义统一结果的目的是让结果变得更加规范,以上就是谷粒项目的几个过程
支付系统---微信支付14----创建案例项目---介绍,第二步引入Swagger,接口文档和测试页面生成工具,定义统一结果的目的是让结果变得更加规范,以上就是谷粒项目的几个过程
|
7月前
|
API
23_Swagger接口文档
23_Swagger接口文档
72 0
|
7月前
|
Java Maven
(knife4j)Swagger-JAVAapi文档生成器
(knife4j)Swagger-JAVAapi文档生成器
56 1
|
7月前
|
前端开发 搜索推荐 Java
springboot集成swagger knife4j 最详细的步骤 手把手教你继承swagger
springboot集成swagger knife4j 最详细的步骤 手把手教你继承swagger
624 0
springboot集成swagger knife4j 最详细的步骤 手把手教你继承swagger
|
7月前
|
前端开发 应用服务中间件 nginx
使用swagger和knife4j生成的接口文档在浏览器中输入地址后报404错误
使用swagger和knife4j生成的接口文档在浏览器中输入地址后报404错误
557 0