Swagger的使用方式、常用注解
一、介绍
使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具就可以做到生成各种格式的接口文档，以及在线接口调试页面等等.官网: https://swagger.io/
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>3.0.2</version> </dependency>
二、使用方式
操作步骤
1、导入knife4j的maven坐标
在项目的pom.xml文件中添加以下依赖坐标：
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>
2、导入knife4j相关配置类:
在Spring Boot的配置文件（如application.yml或application.properties）中添加以下配置项：
knife4j: swagger-ui: enabled: true # 是否启用Swagger-UI，默认为true title: API文档 # 文档标题 description: 接口文档 # 文档描述
3、设置静态资源，否则接口文档页面无法访问
为了能够访问到Swagger生成的接口文档页面，需要配置静态资源映射。示例代码如下：
@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("doc.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
4、在过滤器Filter中设置不需要处理的请求路径
有时候，我们可能需要设置一些不需要被Swagger处理的请求路径。这可以通过自定义Filter来实现。示例代码如下：
@Component public class SwaggerFilter implements Filter { @Override public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException { HttpServletRequest request = (HttpServletRequest) servletRequest; if (request.getRequestURI().startsWith("/exclude")) { // 不处理的请求路径，直接放行 filterChain.doFilter(servletRequest, servletResponse); } else { // 其他请求路径由Swagger处理 // ... } } // ... }
3、Swagger常用注解
注解
说明
@Api
用在请求的类上，例如Controller，表示对类的说明
@ApiModel
用在类上，通常是实体类，表示一个返回响应数据的信息
@ApiModelProperty
用在属性上，描述响应类的属性
@ApiOperation
用在请求的方法上，说明方法的用途、作用
@ApilmplicitParams
用在请求的方法上，表示一组参数说明
@ApilmplicitParam
用在@ApilmplicitParams注解中，指定一个请求参数的各个方面
