Swagger 是一组用于设计、构建、文档化和使用 RESTful Web 服务的开源工具和框架。它允许开发团队设计、构建和测试 API，并提供易于理解的文档，以便开发人员和消费者能够快速了解和使用 API。Swagger 通常与各种编程语言和框架一起使用，以简化 API 的开发和维护过程。
第一步：用IDEA搭建一个Spring Boot项目 （够从0了吧）
1.文件==>项目==>新建项目，这里新建一个Spring项目
2.下一步，选择版本以及所需的依赖，然后完成项目创建，进去等待依赖加载完毕。
3.如果不出以外的的话，建立后的项目文件目录应该为：
第二步：添加Swagger相关依赖
1.打开上图pom.xml文件，添加如下三个依赖：
<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>knife4j-spring-boot-starter</artifactId>
<version>2.0.8</version>
</dependency>
2.接着准备配置一下application.properties：主要是JDBC的一些配置
#将路径替换为你的路径
spring.datasource.url=jdbc:mysql://localhost:3306/food?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8&useSSL=false&allowMultiQueries=true
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driverClassName = com.mysql.cj.jdbc.Driver
然后准备配置文件：
3.在com.swaggertest下新建config文件夹，然后新建SwaggerConfig和WebMvcConfigurer两个JAVA文件
4.点击SwaggerConfig，配置为如下，你粘贴之后大概率会全都是红的，需要一个一个导入类，如果你发现无法导入类，那就是你的依赖没有加载完毕，右键pom选择meaven然后重构
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 通过.select()方法，配置扫描哪些API接口,RequestHandlerSelectors配置如何扫描接口
.select()
//any() // 扫描所有，项目中的所有接口都会被扫描到
//none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
//withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
//withClassAnnotation(final Class<? extends Annotation> annotation)
//basePackage(final String basePackage) // 根据包路径扫描接口
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //添加ApiOperiation注解的被扫描
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
Contact contact = new Contact("加洛斯", "666", "[email protected]");
return new ApiInfo(
"文档标题",
"文档标题的描述",
"版本1.0",
"urn:tos",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
类似于如下情况的话，重构pom文件
右键pom，最底下选择maven，重新加载项目,然后就会出现如下可以导入类
这个要注意，选择service：
配置好后如下图：
5.接下来配置WebMvcConfigurer
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
/** 配置knife4j 显示文档 */
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
/**
* 配置swagger-ui显示文档
*/
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
/** 公共部分内容 */
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
到此准备工作已经做的差不多了，但是后续也会有一些错误，我们碰到后一 一解决。
第三步：启动SpringBoot
1.启动springboot的启动类，访问http://localhost:8080/doc.html即可看到如下接口文档
你也有可能会遇到：解决办法就是用谷歌浏览器试试，这倒霉微软自带的浏览器不知道怎么个事。
当然你也有可能会碰到如下情况
你会看到网上一堆人说你什么启动类位置不对，你可以检查一下位置，但是多半没有用，最有用的办法是在pom文件中检查一下上面那三个依赖两个swagger和一个knife4j你有没有添加以及在application.properties添加一句话：spring.mvc.pathmatch.matching-strategy=ant_path_matcher
到此为止，配置项完毕。接下来看看如何简单的使用一下Swagger。
**第四步：使用swagger **
1.我们新建一个entity包，在此包下建立一个食物实体类：Food，以及foodtype 注意注意：实体类一定要遵循小驼峰命名法，一定要遵循小驼峰命名法，一定要遵循小驼峰命名法！！
要不然会出现无法显示@ApiModelProperty的值的情况
注解介绍：@ApiModel(value = "类别名") 作用在实体类上 @ApiModelProperty作用在实体类的属性上（暂时先知道这两个就行，其他的在学习完配置之后研究）
@Data
@ApiModel(value = "食物类Model")
public class food {
@ApiModelProperty(value = "食物ID")
private String foodId;
@ApiModelProperty(value = "食物名称")
private String foodName;
@ApiModelProperty(value = "食物种类ID")
private String foodTypeId;
@ApiModelProperty(value = "食物种类名")
private String foodTypeName;
public food(String foodId, String foodName, String foodTypeId, String foodTypeName) {
this.foodId = foodId;
this.foodName = foodName;
this.foodTypeId = foodTypeId;
this.foodTypeName = foodTypeName;
}
}
@Data
@ApiModel(value = "食物种类Model")
public class foodtype {
@ApiModelProperty(value = "食物种类ID")
private String foodTypeId;
@ApiModelProperty(value = "食物种类名")
private String foodTypeName;
@ApiModelProperty(value = "食物种类所属列表")
private List<food> foodLists;
}
2.新建Controller包下的foodcontroller，然后配置好相关注解，同样配置如下注解@Api以及@ApiOperation（注解具体有什么用在往后学习时讲解，可以去看看别的大佬文章这里不多赘述）
@RestController
@Api(value = "食物Controller", tags = { "获取食物相关接口" })
@RequestMapping(value = "/food")
public class foodController {
@ApiOperation(value = "获取食物种类类")
@GetMapping("/getFoodtype")
public foodtype test2() throws Exception {
return null;
}
@ApiOperation(value = "获取食物类")
@GetMapping("/getFood")
public List<food> test1() throws Exception {
//使用构造函数模拟一个查询的数据方便测试
food food = new food("1", "锅包肉","1", "肉类");
List<food> foodList = new ArrayList<food>();
foodList.add(food);
return foodList;
}
}
3.到此为止我们的注解就搭建起来了，接下来我们看看效果，访问：http://localhost:8080/doc.html#/home 我们首先能看到Model
这里面的Model是我们在Controller中@ApiOperation注解中使用到了的才会显示，如果你定义了一个Model但是Controller层中的ApiOperation注解并没有用到这个Model，他就并不会显示在这里，我们来看看效果：
接下来看看Controller层，可以看到有我们刚刚定义的两个接口：
可以看到功能很强大，接下来看看接口的测试，我们刚刚用构造函数模拟了一个，看看返回如何：
到此我们的基础Swagger就搭建成功了，但是在实际开发的过程中仅仅使用这些还是远远不够的，后面我会将常用的Swagger注解讲解给大家，如果在搭建Swagger中遇到了哪些难题也欢迎各位留言，如果觉得有用可以点个赞,谢谢各位！！！！！
版权归原作者 加洛斯 所有， 如有侵权，请联系我们删除。