Swagger：手把手教你从0开始配置idea中swagger，全步骤配图文版。

Swagger 是一组用于设计、构建、文档化和使用 RESTful Web 服务的开源工具和框架。它允许开发团队设计、构建和测试 API，并提供易于理解的文档，以便开发人员和消费者能够快速了解和使用 API。Swagger 通常与各种编程语言和框架一起使用，以简化 API 的开发和维护过程。

第一步：用IDEA搭建一个Spring Boot项目 （够从0了吧）

1.文件==>项目==>新建项目，这里新建一个Spring项目

2.下一步，选择版本以及所需的依赖，然后完成项目创建，进去等待依赖加载完毕。

3.如果不出以外的的话，建立后的项目文件目录应该为：

第二步：添加Swagger相关依赖

1.打开上图pom.xml文件，添加如下三个依赖：

   io.springfox
   springfox-swagger2
   2.7.0


   io.springfox
   springfox-swagger-ui
   2.7.0


  com.github.xiaoymin
  knife4j-spring-boot-starter
  2.0.8

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 annotation)
                // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                //withClassAnnotation(final Class 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即可看到如下接口文档

 2.访问http://localhost:8080/swagger-ui.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 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 test1() throws Exception {
        //使用构造函数模拟一个查询的数据方便测试
        food food = new food("1", "锅包肉","1", "肉类");
        List foodList = new ArrayList();
        foodList.add(food);
        return foodList;
    }
}

3.到此为止我们的注解就搭建起来了，接下来我们看看效果，访问：http://localhost:8080/doc.html#/home       我们首先能看到Model

这里面的Model是我们在Controller中@ApiOperation注解中使用到了的才会显示，如果你定义了一个Model但是Controller层中的ApiOperation注解并没有用到这个Model，他就并不会显示在这里，我们来看看效果：

接下来看看Controller层，可以看到有我们刚刚定义的两个接口：

可以看到功能很强大，接下来看看接口的测试，我们刚刚用构造函数模拟了一个，看看返回如何：

到此我们的基础Swagger就搭建成功了，但是在实际开发的过程中仅仅使用这些还是远远不够的，后面我会将常用的Swagger注解讲解给大家，如果在搭建Swagger中遇到了哪些难题也欢迎各位留言，如果觉得有用可以点个赞,谢谢各位！！！！！