SpringBoot集成swagger(3.0.0版本)

河南循中网络科技有限公司 - 精心创作,详细分解,按照步骤,均可成功!


文章目录

  • swagger介绍
  • 学习资料
  • Swagger配置
  • !!到这里,swagger则配置完成,接下来是测试!!
  • 结合[MyBatisPlus代码生成器](https://blog.csdn.net/ChinaYangJu/article/details/126209506),测试Swagger
    • mp的pom文件
    • system的pom文件
    • 修改启动类
  • 创建测试类测试swagger
  • swagger注解


swagger介绍

一般开发人员在对接前后端的时候,都需要提供相应的接口文档。但对于后端来说,编写接口文档是非常费事费力的,有时候甚至写文档所损耗的时间比写代码付出的还要多,并且还会经常因为没有及时更新,导致前端对接的时候,就会出现实际接口与文档不一致,而且手写接口文档还容易出错,而swagger则是能很好的解决了这个痛点。

Swagger 是一个规范完整的框架,用于生成、描述、调用和可视化 RESTful 风格的Web服务。可用作于接口的文档在线自动生成和功能的测试。

学习资料

【【狂神说Java】一小时掌握Swagger技术-哔哩哔哩】
swagger官网

Swagger配置

  1. 引入swagger的jar包,注意需要web工程。
	<!-- 版本控制 -->
    <properties>
        <!-- swagger -->
        <springfox-boot-starter.version>3.0.0</springfox-boot-starter.version>
    </properties>

    <!-- 引入的jar包 -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>${springfox-boot-starter.version}</version>
        </dependency>
    </dependencies>
  1. 创建SwaggerConfig配置类。
package com.xz.swagger;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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 java.util.ArrayList;

/**
 * swagger配置
 * 访问地址:项目路径前缀/swagger-ui/index.html
 */
@Configuration
@EnableWebMvc
public class SwaggerConfig {

    /**
     * 配置了swagger的Docket的bean实例
     * 此方法可配置多个,复制后改个方法名即可,用于分组
     * @return
     */
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否处在自己设定的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("河南循中网络科技有限公司")
                .apiInfo(apiInfo())
                .enable(flag)//enable是否启动Swagger,如果为false,则Swagger不能在浏览器中访问
                .select()
                //RequestHandlerSelectors.basePackage("包名")  单包扫描
                //RequestHandlerSelectors.basePackage("包名").or(RequestHandlerSelectors.basePackage("包名"))  多包扫描
                .apis(RequestHandlerSelectors.basePackage("com.xz.controller.miniPro"))
                //加了ApiOperation注解的类,才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

    /**
     * 配置swagger信息=apiInfo
     * @return
     */
    private ApiInfo apiInfo(){
        Contact contact = new Contact("项目组成员", "", "[email protected]");
        return new ApiInfo(
                "swaggerAPI文档",
                "在高处有如临深渊的谨慎,在低谷有仰望星空的勇气。",
                "v1.0",
                "",
                contact,
                "Apache Tomcat/9.0.64",
                "https://tomcat.apache.org/tomcat-9.0-doc/building.html",
                new ArrayList<>());
    }
}

!!到这里,swagger则配置完成,接下来是测试!!

结合MyBatisPlus代码生成器,测试Swagger

SpringBoot集成swagger(3.0.0版本)_第1张图片

mp的pom文件

子模块mp需引用分模块common,因为swagger的jar包和配置都存在与common模块中。

<?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>
    <groupId>com.xz</groupId>
    <artifactId>mp</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>mp</name>
    <description>河南循中网络科技有限公司 - MyBatis-Plus自动化</description>

    <!-- 子模块打包类型必须为jar -->
    <packaging>jar</packaging>

    <!-- parent指明继承关系,给出被继承的父项目的具体信息 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <!-- 版本控制 -->
    <properties>
        <java.version>1.8</java.version>
        <!-- 实体类注解 -->
        <lombok.version>1.18.24</lombok.version>
        <!-- 数据库 -->
        <druid-spring-boot-starter.version>1.2.11</druid-spring-boot-starter.version>
        <!-- mybatis plus -->
        <mybatis-plus-boot-starter.version>3.5.1</mybatis-plus-boot-starter.version>
        <!-- mybatis代码生成器 -->
        <mybatis-plus-generator.version>3.5.3</mybatis-plus-generator.version>
        <!-- mybatis代码生成器,所需要的“velocity模板引擎” -->
        <velocity-engine-core.version>2.3</velocity-engine-core.version>
    </properties>

    <!-- 引入的jar包 -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- 引用分模块common -->
        <dependency>
            <groupId>com.xz</groupId>
            <artifactId>common</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>

        <!-- 实体类注解 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
        </dependency>

        <!-- 数据库 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>${druid-spring-boot-starter.version}</version>
        </dependency>

        <!-- mybatis plus -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatis-plus-boot-starter.version}</version>
        </dependency>

        <!-- mybatis代码生成器 -->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-generator</artifactId>
            <version>${mybatis-plus-generator.version}</version>
        </dependency>

        <!-- mybatis代码生成器,所需要的“velocity模板引擎” -->
        <dependency>
            <groupId>org.apache.velocity</groupId>
            <artifactId>velocity-engine-core</artifactId>
            <version>${velocity-engine-core.version}</version>
        </dependency>
    </dependencies>

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

</project>

system的pom文件

子模块system需引用分模块mp

    
        com.xz
        mp
        0.0.1-SNAPSHOT
    
<?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>
    <groupId>com.xz</groupId>
    <artifactId>system</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>system</name>
    <description>河南循中网络科技有限公司 - 程序</description>

    <!-- 子模块打包类型必须为jar -->
    <packaging>jar</packaging>

    <!-- parent指明继承关系,给出被继承的父项目的具体信息 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <!-- 版本控制 -->
    <properties>
        <java.version>1.8</java.version>
    </properties>

    <!-- 引入的jar包 -->
    <dependencies>
        <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>

        <!-- 引用分模块common -->
        <dependency>
            <groupId>com.xz</groupId>
            <artifactId>common</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>

        <!-- 引用分模块mp -->
        <dependency>
            <groupId>com.xz</groupId>
            <artifactId>mp</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>
    </dependencies>

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

</project>

修改启动类

只为启动起来后,更方便查阅相关URL

package com.xz;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.core.env.Environment;

import java.net.InetAddress;

@SpringBootApplication
public class SystemApplication {

    public static void main(String[] args) {
        try {
            ConfigurableApplicationContext application = SpringApplication.run(SystemApplication.class, args);
            Environment env = application.getEnvironment();
            String ip = InetAddress.getLocalHost().getHostAddress();
            String port = env.getProperty("server.port");
            System.out.println("\n----------------------------------------------------------\n\t" +
                    "应用程序 系统平台端 正在运行! 访问地址:\n\t" +
                    "本机: \t\t http://localhost:" + port + "/\n\t" +
                    "外部访问: \t http://" + ip + ":" + port + "/\n\t" +
                    "Swagger文档: \t http://" + ip + ":" + port + "/swagger-ui/index.html\n" +
                    "----------------------------------------------------------");
        }catch (Exception e){
            e.printStackTrace();
        }
    }

}

创建测试类测试swagger

SpringBoot集成swagger(3.0.0版本)_第2张图片
SpringBoot集成swagger(3.0.0版本)_第3张图片

swagger注解

swagger是通过注解表明该接口需要生成文档,其中包含(接口名、请求方法、参数、返回信息)

如下注解介绍,只介绍有用的干货,无用的信息,暂不介绍

注解 说明
@Api(tags=“说明该类的作用”) 修饰整个类,描述Controller的作用
@ApiOperation(value = “说明方法的作用”,notes = “方法的备注说明”,response = 接口返回参数类型) 修饰一个类下的一个方法,描述Controller下接口的作用
@ApiImplicitParam(name = “参数名”,value = “参数说明”,dataType = “字段类型”,defaultValue = “参数的默认值”,required = 参数是否必传true、false) 修饰一个类下的一个方法,当只有一个请求参数时使用
@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam()}) 修饰一个类下的一个方法,当有多个请求参数时,配合@ApiImplicitParam一起使用
@ApiModel(value=“为模型提供备用名称”, description=“提供详细的描述”) 修饰整个类,描述模型的作用,用于模型类
@ApiModelProperty(value = “属性简要说明”) 修饰整个类,描述模型下属性的作用,用于模型类的属性上

你可能感兴趣的:(springBoot系列,spring,boot,mybatis,java)