提示:本文主要是对网上帖子的整理和对自己踩坑的总结,如有侵权请及时联系我。
文章目录
前言
小白踩了很多坑,服了。若有写的不对的地方,请大佬指正。
一、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错误。。。
如果有大佬了解原因可以评论,万分感谢!!!
后续如果我学的更多了我会继续更的。