Swagger 的作用与使用详解

文章目录

• 前言
• 一、Swagger 的作用
• 二、Swagger 的优点
• 三、使用步骤
  • 1.导入 knife4j的maven坐标
  • 2.导入knife4j相关配置（WebMvcConfig）
  • 3.设置静态资源映射
  • 4.在拦截器中设置不需要处理的请求路径
• 四、Swagger 常用注解
• 总结

---

前言

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

目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。
 

---

一、Swagger 的作用

根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是 在开发接口时可以通过swagger 将接口文档定义好，同时也方便以后的维护。

在没有swagger之前，我们可以使用word，excel等功能来书写接口定义文档，但又有一个弊端，即： 在接口发送改变时需要及时的同步接口文档，否则实际的接口与接口文档不相符，则接口文件就失去了作用，甚至会起到反作用。

二、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.设置静态资源映射

设置静态资源映射(WebMvcConfig类中的addResourceHandlers方法) ,否则接口文档页面无法访问

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

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

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

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

四、Swagger 常用注解

 

---

总结

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