教你springboot配置swagger实现接口文档

快来打我* 2024-04-06 09:41 30阅读 0赞

## 前言 ##

什么是Swagger?  
在正式要配置它之前我们应该要对它有所了解，所谓`swagger`，简单说就是专门配置接口文档说明的一个依赖工具。  
**swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。**  
以上也就是它的作用，别的就不多说了，需要了解更多就自己去百度查找资料，最重要的还是如何去配置和使用它

## 创建springboot项目 ##

那么,我们一开始应该要有一个springboot项目，本次我会从零开始构建。  
本次使用的是`IDEA`进行创建springboot项目

### **FILE—>NEW—>PROJECT**创建项目 ###

![在这里插入图片描述][819df2764c9f49f29cc5a6e43b1d93ee.png]

### **选择Maven类型，并下一步输入项目名、组织名**然后点击FINISH创建 ###

![在这里插入图片描述][d140944705fe4f64b4cfc6e07f7a872b.png]  
![在这里插入图片描述][1a112113bbb54f5fbdfa3e09bfc3ef8f.png]  
初始项目结构如图  
![在这里插入图片描述][538494c8da3a47389d37eb5538d18a89.png]

### 创建不同层级文件夹并搭建框架 ###

搭建完框架的项目截图  
![在这里插入图片描述][7c82f26dd6e94ed28d9eb8fcbd95743c.png]

`testMapper`代码

package com.testSwagger.mapper;
    import org.apache.ibatis.annotations.Mapper;
    @Mapper
    public interface testMapper {
        
    }

`SwaggerApplication`代码

package com.testSwagger;
    import org.mybatis.spring.annotation.MapperScan;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    // 声明springboot
    @SpringBootApplication
    // 指定连接数据库的mapper区
    @MapperScan("com.testSwagger.mapper")
    public class SwaggerApplication {
        
        public static void main(String[] args) {
        
            SpringApplication.run(SwaggerApplication.class,args);
        }
    }

`application.yml`代码

# 指定启动路径
    server:
      port: 9111
      servlet:
        # 项目的路径，配置如下之后，它的路径为http:locahost:9111/swagger
        context-path: /swagger
    # 为启动项目，需要配置一个数据库进行连接
    spring:
      datasource:
        driver-class-name: com.mysql.jdbc.Driver
        url: jdbc:mysql://数据库url
        username: 连接数据库的用户名
        password: 连接数据库的密码

`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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
        <modelVersion>4.0.0</modelVersion>
    
        <groupId>org.example</groupId>
        <artifactId>swagger</artifactId>
        <version>1.0-SNAPSHOT</version>
    
        <properties>
            <maven.compiler.source>8</maven.compiler.source>
            <maven.compiler.target>8</maven.compiler.target>
            
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        </properties>
        <parent>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>2.4.5</version>
        </parent>
        <dependencies>
            
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
            
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-boot-starter</artifactId>
                <version>3.4.3</version>
            </dependency>
            
            <dependency>
                <groupId>mysql</groupId>
                <artifactId>mysql-connector-java</artifactId>
                <version>8.0.26</version>
            </dependency>
    
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.16.18</version>
                <optional>true</optional>
            </dependency>
        </dependencies>
        
        <build>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
        </build>
    </project>

以上，我们基础的springboot项目就搭建好了，接下来正式的去实现swagger

## 配置swagger ##

首先得说一下它的官方文档链接，不过它都是英文不好懂，大家可跟着我的步骤去构建

[swagger文档链接][swagger]

本次项目使用的是`swagger2`  
**同时说一点： swagger分为swagger2 和swagger3两个常用版本。二者区别不是很大，主要对于依赖和注解进行了优化。swagger2需要引入2个jar包，swagger3只需要一个，用起来没有什么大的区别。下面以swagger2为例。**

`ps:` **如果你需要使用的是swagger3或者更高版本  
请在application.yml文件添加如下配置**

spring:
        mvc:
            path match:
                matching-strategy: ant_path_matcher

### 添加swagger的pom依赖 ###

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

### 添加config配置 ###

在`config`文件夹下，创建swagger配置的java文件  
![在这里插入图片描述][7e344ddf42aa477e9ae3c597ed5dc0e3.png]  
`更新于2023-01-15 09:11:35`

package com.testSwagger.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfiguration {
        
        @Bean
        public Docket createRestApi() {
        
            return new Docket(DocumentationType.SWAGGER_2)
                    .pathMapping("/")
                    .enable(true)
                    .host("localhost:9111")
                    .select()
                    //这里指定Controller扫描包路径(项目路径也行)
                    .apis(RequestHandlerSelectors.basePackage("com.testSwagger.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("swagger测试文档")
                    .description("swagger测试的API文档-swageer2")
                    .contact(new Contact("相与还","http://localhost:9111/swagger/doc.html","a1947934569@163.com"))
                    .termsOfServiceUrl("http://localhost:9111/swagger/doc.html")
                    .version("1.0.0")
                    .build();
        }
    }

### 创建swagger文档案例 ###

#### 新建实体类并添加swagger注解 ####

在这里分别使用了 `@ApiModel`注解和 `@ApiModelProperty` 注解定义了实体的名称和字段的名称，方便生成接口文档时展示。

添加实体类的swagger注解,名称自取  
![在这里插入图片描述][8edf85510d9449cca3d248388184ad0c.png]

package com.testSwagger.bean;
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @Data
    @ApiModel("swagger实体类")
    public class BeanTest {
        
        @ApiModelProperty("名称")
        private String name;
        @ApiModelProperty("年龄")
        private String age;
    }

#### 创建controller并添加swagger注解 ####

这里使用了`@Api`注解和`@ApiOperation`注解分别标注了接口组名和接口的名称。

新建一个`controller`文件，任意取名  
![在这里插入图片描述][c19078b4890643ae8967fe41f09fbe40.png]

package com.testSwagger.controller;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    @RequestMapping("/swagger")
    @Api(value = "测试controller",tags = {
        "接口"})
    public class SwaggerController {
        
    
        @ApiOperation("接口1作用")
        @GetMapping("controller1")
        public String controller1() {
        
            return "测试接口1";
        }
    
        @ApiOperation("接口2作用")
        @PostMapping("controller2")
        public String controller2(){
        
            return "测试接口2";
        }
    }

## 访问接口文档 ##

到这个地方，我们就可以访问我们的接口文档了  
前面我的yml配置的访问地址是/swagger  
![在这里插入图片描述][e3f59d56ede64f70be1da7ae5ccc31d6.png]

`更新于2023-01-15 09:12:49`  
因此`swagger2`访问的链接是:

http://localhost:9111/swagger/swagger-ui.html

假如你使用的是`swagger3`  
那么按照本项目的配置访问链接为

http://localhost:9111/swagger/swagger-ui/index.html

运行后的项目截图为:  
![在这里插入图片描述][970385f2e0e944fabd9387088fe4fa3e.png]  
![在这里插入图片描述][af644ef495b748b189858c8b393dfcb9.png]  
`更新于2023-01-15 09:14:54`

## 进阶 ##

以上，你会发现，它的界面太丑了，看上去体验不是很好，那么我接下来，将变更它的UI

#### 引入swagger的UI依赖 ####

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

然后你直接访问链接  
`http://localhost:9111/swagger/doc.html`

也可以按照代码

private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("swagger测试文档")
                    .description("swagger测试的API文档-swageer2")
                    .contact(new Contact("相与还","http://localhost:9111/swagger/doc.html","a1947934569@163.com"))
                    .termsOfServiceUrl("http://localhost:9111/swagger/doc.html")
                    .version("1.0.0")
                    .build();
        }

点击swagger基础界面的  
`Terms of service`也可以跳转到美化后的Swagger的UI界面  
虽然当前配置下可以点击  
`相与还-Website`进行跳转到美化后的Swagger的UI界面，但是一般情况它可能用来写自己个人网址还是什么比较多吧，也可以和我一样的写法。  
![在这里插入图片描述][026d56dc8be2423aadf83a551f757ad0.png]  
然后美化后的UI截图如下:  
![在这里插入图片描述][4019a3f1a26049dd9358c1aff0d01a4d.png]  
![在这里插入图片描述][f3c3775a318740fcb6e2d661238741c3.png]

明显比之前的好看很多，到现在已经可以进行开发完成接口文档了。

## 问题处理 ##

假如出现访问swagger接口文档失败，报错404，则新建一个配置文件，配置文件名称任意，继承自`WebMvcConfigurer`  
代码例子:

public class exampleConfig implements WebMvcConfigurer {
        
    	    /**
         * 防止/swagger-ui.html 404错误
         *
         * @param registry
         */
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
        
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            // 开放优化后的swagger的ui访问路径
            registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

## 结语 ##

以上就是swagger文档的配置和使用步骤，如有新内容将在本文章更新

[819df2764c9f49f29cc5a6e43b1d93ee.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/ad86edb5af134727a57d02435f62faee.png
[d140944705fe4f64b4cfc6e07f7a872b.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/224ef030e7dd406a9ac39cc2eb06ef2f.png
[1a112113bbb54f5fbdfa3e09bfc3ef8f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/32d035f9296f4157926e4c1a67f29731.png
[538494c8da3a47389d37eb5538d18a89.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/86263357d325417bbca6b4968487c189.png
[7c82f26dd6e94ed28d9eb8fcbd95743c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/3831b17f49d54eb596e3871a1226127d.png
[swagger]: https://swagger.io/docs/
[7e344ddf42aa477e9ae3c597ed5dc0e3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/ab80a6e695464bbfb0c7fba58ee410f3.png
[8edf85510d9449cca3d248388184ad0c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/fe64ca3a4e4a407e9b367caf2a25fd0d.png
[c19078b4890643ae8967fe41f09fbe40.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/48960bca099e4f02a9084befb84d11c0.png
[e3f59d56ede64f70be1da7ae5ccc31d6.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/ce977d60cbe344ccb023cd0c38e7afd8.png
[970385f2e0e944fabd9387088fe4fa3e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/4c6e6cd5aa7e479c961b0afa35eb46aa.png
[af644ef495b748b189858c8b393dfcb9.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/635e2f4bc7394d339fe0b99d4dcfaab6.png
[026d56dc8be2423aadf83a551f757ad0.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/54e22dc95ca946cdaf95623f5bca1949.png
[4019a3f1a26049dd9358c1aff0d01a4d.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/e7acba4689014eb2bdd932dc34151922.png
[f3c3775a318740fcb6e2d661238741c3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/06/ab8c3396e61042a69e7069ace3464f76.png