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

文章目录

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("项目组成员", "", "xunzhongkeji2022@163.com");
        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

在这里插入图片描述

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

    <dependency>
        <groupId>com.xz</groupId>
        <artifactId>mp</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>

<?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

在这里插入图片描述
在这里插入图片描述

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 = “属性简要说明”)修饰整个类，描述模型下属性的作用，用于模型类的属性上
# spring boot # java
Logo
华为云开发者联盟

为开发者提供学习成长、分享交流、生态实践、资源工具等服务，帮助开发者快速成长。

更多推荐

cover

openEuler系统通过shell脚本安装openGauss 5.0.0企业版

avatar 华为云开发者联盟
cover

云原生多云多集群Karmada｜2024开源之夏8项课题邀您共创

avatar 华为云开发者联盟
cover

全球厂商之最，华为17篇论文入选国际数据库顶会ICDE

avatar 华为云开发者联盟