SpringBoot集成swagger（3.0.0版本）

技术人生-小草 2023-08-22 原文

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

文章目录

swagger介绍

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

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

学习资料

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

Swagger配置

引入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>

创建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 = “属性简要说明”)	修饰整个类，描述模型下属性的作用，用于模型类的属性上

有关SpringBoot集成swagger（3.0.0版本）的更多相关文章

ruby-on-rails - 项目升级后 Pow 不会更改 ruby 版本 - 2
我在我的Rails项目中使用Pow和powifygem。现在我尝试升级我的ruby版本(从1.9.3到2.0.0，我使用RVM)当我切换ruby版本、安装所有gem依赖项时，我通过运行railss并访问localhost:3000确保该应用程序正常运行以前，我通过使用pow访问http://my_app.dev来浏览我的应用程序。升级后，由于错误Bundler::RubyVersionMismatch:YourRubyversionis1.9.3,butyourGemfilespecified2.0.0，此url不起作用我尝试过的:重新创建pow应用程序重启pow服务器更新战俘
ruby-on-rails - 在 ruby .gemspec 文件中，如何指定依赖项的多个版本？ - 2
我正在尝试修改当前依赖于定义为activeresource的gem:s.add_dependency"activeresource","~>3.0"为了让gem与Rails4一起工作，我需要扩展依赖关系以与activeresource的版本3或4一起工作。我不想简单地添加以下内容，因为它可能会在以后引起问题:s.add_dependency"activeresource",">=3.0"有没有办法指定可接受版本的列表？~>3.0还是~>4.0？最佳答案根据thedocumentation,如果你想要3到4之间的所有版本，你可以这
ruby-on-rails - 如何使辅助方法在 Rails 集成测试中可用？ - 2
我在app/helpers/sessions_helper.rb中有一个帮助程序文件，其中包含一个方法my_preference，它返回当前登录用户的首选项。我想在集成测试中访问该方法。例如，这样我就可以在测试中使用getuser_path(my_preference)。在其他帖子中，我读到这可以通过在测试文件中包含requiresessions_helper来实现，但我仍然收到错误NameError:undefinedlocalvariableormethod'my_preference'.我做错了什么？require'test_helper'require'sessions_hel
ruby-on-rails - 如果我将 ruby 版本 2.5.1 与 rails 版本 2.3.18 一起使用会怎样？ - 2
如果我使用ruby版本2.5.1和Rails版本2.3.18会怎样？我有基于rails2.3.18和ruby1.9.2p320构建的rails应用程序，我只想升级ruby的版本，而不是rails，这可能吗？我必须面对哪些挑战？最佳答案 GitHub维护apublicfork它有针对旧Rails版本的分支，有各种变化，它们一直在运行。有一段时间，他们在较新的Ruby版本上运行较旧的Rails版本，而不是最初支持的版本，因此您可能会发现一些关于需要向后移植的有用提示。不过，他们现在已经有几年没有使用2.3了，所以充其量只能让更
ruby-on-rails - 我如何将 Hoptoad 与 DelayedJob 和 DaemonSpawn 集成？ - 2
我一直很高兴地使用DelayedJob习惯用法:foo.send_later(:bar)这会调用DelayedJob进程中对象foo的方法bar。我一直在使用DaemonSpawn在我的服务器上启动DelayedJob进程。但是...如果foo抛出异常，Hoptoad不会捕获它。这是任何这些包中的错误...还是我需要更改某些配置...或者我是否需要在DS或DJ中插入一些异常处理来调用Hoptoad通知程序？回应下面的第一条评论。classDelayedJobWorker 最佳答案尝试monkeypatchingDelayed::W
ruby-on-rails - 获取 inf-ruby 以使用 ruby 版本管理器 (rvm) - 2
我安装了ruby版本管理器，并将RVM安装的ruby实现设置为默认值，这样'哪个ruby'显示'~/.rvm/ruby-1.8.6-p383/bin/ruby'但是当我在emacs中打开inf-ruby缓冲区时，它使用安装在/usr/bin中的ruby。有没有办法让emacs像shell一样尊重ruby的路径？谢谢! 最佳答案我创建了一个emacs扩展来将rvm集成到emacs中。如果您有兴趣，可以在这里获取:http://github.com/senny/rvm.el
ruby-on-rails - 如何在发布新的 Ruby 或 Rails 版本时收到通知？ - 2
有人知道在发布新版本的Ruby和Rails时收到电子邮件的方法吗？他们有邮件列表，RubyonRails有一个推特，但我不想听到那些随之而来的喧嚣，我只想知道什么时候发布新版本，尤其是那些有安全修复的版本。最佳答案从therailsblog获取提要.http://weblog.rubyonrails.org/feed/atom.xml 关于ruby-on-rails-如何在发布新的Ruby或Rails版本时收到通知？，我们在StackOverflow上找到一个类似的问题：
【鸿蒙应用开发系列】- 获取系统设备信息以及版本API兼容调用方式 - 2
在应用开发中，有时候我们需要获取系统的设备信息，用于数据上报和行为分析。那在鸿蒙系统中，我们应该怎么去获取设备的系统信息呢，比如说获取手机的系统版本号、手机的制造商、手机型号等数据。1、获取方式这里分为两种情况，一种是设备信息的获取，一种是系统信息的获取。1.1、获取设备信息获取设备信息，鸿蒙的SDK包为我们提供了DeviceInfo类，通过该类的一些静态方法，可以获取设备信息，DeviceInfo类的包路径为：ohos.system.DeviceInfo.具体的方法如下：ModifierandTypeMethodDescriptionstatic StringgetAbiList()Obt
jenkins部署1--jenkins+gitee持续集成 - 2
前置步骤我们都操作完了，这篇开始介绍jenkins的集成。话不多说，看操作1、登录进入jenkins后会让你选择安装插件，选择第一个默认的就行。安装完成后设置账号密码，重新登录。2、配置JDK和Git都需要执行路径，所以需要先把执行路径找到，先进入服务器的docker容器，2.1JDK的路径root@69eef9ee86cf:/usr/bin#echo$JAVA_HOME/usr/local/openjdk-82.2Git的路径root@69eef9ee86cf:/#whichgit/usr/bin/git3、先配置JDK和Git。点击：ManageJenkins>>GlobalToolCon
ruby-on-rails - 安装多个版本的 Rails 会覆盖以前的安装吗？ - 2
如果我一直输入geminstallrails使用不同版本的Rails会怎样？例如，我可以输入:geminstallrails--verson3.2.10或geminstallrails这给了我版本3.2.12。问题每次安装都会覆盖之前的吗？它会删除所有旧文件并添加我正在安装的新版本吗？或者如果我运行它两次，它会保留一些文件吗？我正在使用Ubuntu。最佳答案它将安装两个独立的gem。实际的可执行文件rails将调用最新版本。你可以覆盖它__例如，rails_3.2.10_将执行Rails3.2.10。bundler顺便说一下，如