开发规范(Swagger) + 接口文档

归去来兮辞:japan::japanese_goblin::ice_cream:

前后端开发流程

---

Swagger介绍

使用Swagger只需要按照它的规范去定义接口以及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面

官网：https://swagger.io/

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

---

Swagger使用方式

在这里引入一点小知识

WebMvcConfigurer和 WebMvcConfigurationSupport 都是用来配置 Spring MVC的接口，但是它们有一些不同：

1. WebMvcConfigurer 是一个简单的接口，提供了一组回调方法，用于配置 Spring MVC。您可以实现这个接口并覆盖它的回调方法来配置 Spring MVC。
2. WebMvcConfigurationSupport 是一个特殊的抽象类，实现了 WebMvcConfigurer 接口，并且提供了一组默认实现。您可以扩展这个类并覆盖它的方法来配置 Spring MVC。

总的来说，如果只需要实现一些简单的配置，可以使用 WebMvcConfigurer；如果需要实现更复杂的配置，则可以扩展 WebMvcConfigurationSupport 类。

下面是我原来的SpringMVC配置类

因为需要加入Swagger所以将implements WebMVCConfigurer转为extend WebMvcConfigurationSupport并继续下述操作

1. 导入knife4j 的maven坐标

      <dependency>
      	<groupId>com.github.xiaoymin</groupId>
      	<artifactId>knife4j-spring-boot-starter</artifactId>
      	<version>4.3.0</version>
      </dependency>
   
   2. **在配置类中加入 Knife4j 相关配置**
   
      ~~~java
      @Bean
      public Docket docket() {
      	ApiInfo apiInfo = new ApiInfoBuilder()
      		.title("接口文档标题")
      		.version("2.0")
      		.description("接口文档描述")
      		.build();
      	Docket docket = new Docket(DocumentationType.SWAGGER_2)
      		.apiInfo(apiInfo)
      		.select()
              //指定生成接口需要扫描的包
      		.apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
      		.paths(PathSelectors.any())
      		.build();
      	return docket;
      }

2. 设置静态资源映射，否则接口文档页面无法访问

   /**
    * 设置静态资源映射
    * @param registry
    */
   protected void addResourceHandlers(ResourceHandlerRegistry registry) {
       //doc.html就是我们接口文档的访问路径 
       registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
       registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
   }

---

配置完之后的SpringMVC配置类应该是这样子的

启动项目测试是否能打开接口文档，可以看到接口文档配置成功启动，并且知道SpringBoot项目运行在3000端口

随后打开文档页面，打开浏览器http://localhost:3000/doc.html，可以看到文档页面成功生成啦…

注意事项：

若是打不开页面，检查是否因为

1. 过滤器导致页面无法访问
2. 路由重定向？【可能出现，概率小，几乎不存在】
3. knife4j没有配置好

Swagger常用注解

• 通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解	说明
@Api	用在类上，例如Controller，表示对类的说明
@ApiModel	用在类上，例如entity、DTO、VO
@ApiModelProperty	用在属性上，描述属性信息
ApiOperation	用在方法上，例如Controller的方法，说明方法的用途、作用

示例：

我对如下类、方法、数据模型、模型元数据进行了Api注解

启动项目，查看接口文档的变化，首先查看不添加注释的API文档

添加注解后的生成的API文档更容易阅读