初识Swagger

前言

对于前后端分离开发，可以按以下流程进行：

接口(API接口)就是一个http的请求地址，主要就是去定义:请求路径、请求方式、请求参数、响应数据等内容，如图所示：

Swagger介绍

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

官网: https://swagger.io/

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案

操作步骤:

1. 导入knife4j的maven坐标

<dependency>
    <groupld>com.github.xiaoymin</groupld>
    <artifactld>knife4i-spring-boot-starter</artifactld>
    <version>3.0.2</version>
</dependency>

2. 导入knife4j相关配置类

在WebMvcConfig中挂上两个注解：@EnableSwagger2和@EnableKnife4j

添加两个方法

@Bean
public Docket createRestApi() {
    // 文档类型，返回文档信息，需要更改的只有"com.xxx.controller"
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
            .paths(PathSelectors.any())
            .build();
}

private ApiInfo apiInfo() {
    //描述接口文档
    return new ApiInfoBuilder()
            .title("name")
            .version("version")
            .description("description")
            .build();
}

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

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

若没有添加，接口文档页面无法访问

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

我们通常会在filter中进行一些路径的拦截和放行，在这边需要把我们要放行的路径加进去

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

检验

启动服务器，利用localhost/doc.html（端口号设为80，默认不写，若不是加上端口号）访问

常用注解

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

摘自黑马老师上课ppt，仅作为自身学习笔记，如有错误，请大佬指出