SprinBoot搭建Swagger总结

提示：本文主要是对网上帖子的整理和对自己踩坑的总结，如有侵权请及时联系我。

---

前言

小白踩了很多坑，服了。若有写的不对的地方，请大佬指正。

---

一、Swagger是什么？

我的理解：现在工作大多是前后端分离，一般后端提供接口给前端。怎么判别这个接口是否准确，正常呢？Swagger闪亮登场，可以理解为接口测试工具，用来测试接口返回是否正常。

二、与SpringBoot的整合

1.新建SpringBoot项目

2.引入Swaggery依赖

两个依赖：

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>


		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>

		<!--锦上添花的依赖，可加可不加-->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.9.6</version>
		</dependency>

pom.xml（示例）：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.7.3</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>demo</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>demo</name>
	<description>Demo project for Spring Boot</description>
	<properties>
		<java.version>1.8</java.version>
	</properties>
	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter</artifactId>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>


		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.7.0</version>
		</dependency>

		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>1.9.6</version>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
			<version>RELEASE</version>
			<scope>compile</scope>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

3.SwaggerConfig（对Swagger相关配置，与SpringBoot启动类同目录）

代码如下（示例）：

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restful风格")
                .termsOfServiceUrl("http://localhost:8080")
                .version("1.1")
                .build();
    }
}

注意：.apis(RequestHandlerSelectors.basePackage(“com.example”))填写自己的包路径（我的理解是com.example这个包下的所有文件都能Swagger都能识别到），如果填写有误可能controller会缺失

---

4、加入Controller以便进行测试

Controller类：

@RestController
@Api(value = "Controller", tags = { "Controller访问接口" })
@RequestMapping(value = "/hello")
public class HelloSpringBootController {

    @GetMapping
    public String helloWorld(){
        return "hello,SpringBoot";
    }
}

启动springboot访问网址 ：http://localhost:8080/swagger-ui.html

---

如果你一切顺利的话，恭喜你。当然苦逼的我，永远不可能一帆风顺。

踩坑总结

1、Swagger和SpringBoot版本号不匹配

在SpringBoot的application.properties文件中添加下面：

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

如果是yml文件的话：

mvc:
	pathmatch:
		matching-strategy: ant_path_matcher

2、404问题，至今未解决（提供一篇博主的帖子以供参考）

先上链接：https://juejin.cn/post/7078109157656231944#heading-5
完整代码（将WebMvcConfig 配置类加入到项目中）：

package com.example.demo;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {


    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
    }
}

3、Swagger更换好看UI

在WebMvcConfig 配置类中加入这段代码（当然前文提到的锦上添花的依赖必不可少哦）

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

参考文章

【1】一缕82年的清风大佬的：SpringBoot教程(十六) | SpringBoot集成swagger（全网最全）
【2】公众号_IT老哥大佬的：一分钟搭建springBoot项目，并集成swagger

写在最后

我最后用参考文章【2】搭建出来Swagger了。
我不知道为啥我用IDEA自己生成的SpringBoot项目，死活报404错误。。。
如果有大佬了解原因可以评论，万分感谢！！！
后续如果我学的更多了我会继续更的。