Swagger的使用方式、常用注解

一、介绍

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger衍生出来的一系列项目和工具就可以做到生成各种格式的接口文档，以及在线接口调试页面等等.官网: https://swagger.io/
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

    com.github.xiaoymin
    knife4j-spring-boot-starter
    3.0.2

二、使用方式

操作步骤
1、导入knife4j的maven坐标

在项目的pom.xml文件中添加以下依赖坐标：

    com.github.xiaoymin
    knife4j-spring-boot-starter
    2.0.9

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注解中，指定一个请求参数的各个方面