SpringBoot集成 Swagger

这篇具有很好参考价值的文章主要介绍了SpringBoot集成 Swagger。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

Spring Boot 集成 Swagger 在线接口文档

1、Swagger 简介

1.1 解决的问题

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系变成了 API 接口,所以 API 文档变成了前后端开

发人员联系的纽带,变得越来越重要。

那么问题来了,随着代码的不断更新,开发人员在开发新的接口或者更新旧的接口后,由于开发任务的繁重,往往文档很难持续跟着更新,Swagger 就是用来解决该问题的一款重要的工具,对使用接口的人来说,开发人员不需要给他们提供文档,只要告诉一个 Swagger 地址,即可展示在线的 API 接口文档,除此之外,调用接口的人员还可以在线测试接口数据,同样地,开发人员在开发接口时,同样也可以利用 Swagger 在线接口文档测试接口数据,这给开发人员提供了便利。

1.2 Swagger 官方

打开 Swagger 官网为 https://swagger.io/

主要掌握在 Spring Boot 中如何导入 Swagger 工具来展现项目中的接口文档。

2、Swagger 的 maven 依赖

使用 Swagger 工具,必须要导入 maven 依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
</dependency>

3、Swagger 配置

使用 Swagger 需要进行配置,Spring Boot 中对 Swagger 的配置非常方便,新建一个配置类,Swagger 的配置类上除了添加必要的@Configuration 注解外,还需要添加@EnableOpenApi 注解。

@EnableOpenApi
@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用 Swagger3.0 版本
            // 是否关闭在线文档,生产环境关闭
            .enable(true)
             // 指定构建 api 文档的详细信息的方法
            .apiInfo(apiInfo())
// 指定要生成 api 接口的包路径,这里把 action 作为包路径,生成 controller 中的所有接口 
            .apis(RequestHandlerSelectors.basePackage("com.ma.action"))
            .select() 
            //只 有 在 方 法接口上添加了 ApiOperation 注解
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any()).build().globalResponses(HttpMethod.GET, 
getGlobalResponseMessage())
            .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }
}
// 生成摘要信息
private ApiInfo apiInfo() {
    return new ApiInfoBuilder().title("接口文档") //设置页面标题
    .description("说明信息") 设置接口描述
    .contact(new Contact("yangyang", "http://baidu.com", "yang@yang.com")) //设置联系方式
    .version("1.0") //设置版本
    .build(); //构建
}

在该配置类中已经使用注释详细解释了每个方法的作用了。到此已经配置好 Swagger 了。现在可以测试一下

配置有没有生效,启动项目,在浏览器中输入 http://localhost:8080/test/swagger-ui/,即可看到 swagger 的

接口页面,说明 Swagger 集成成功。

对照 Swagger 配置文件中的配置,可以很明确的知道配置类中每个方法的作用。这样就很容易理解和掌握Swagger 中的配置了,也可以看出,其实 Swagger 配置很简单。

有可能在配置 Swagger 时关不掉,是因为浏览器缓存引起的,清空一下浏览器缓存即可解决问题。

相关配置

spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

4、Swagger 的使用

已经配置好了 Swagger,并且也启动测试了一下,功能正常,下面可以开始使用 Swagger,重点要掌握 Swagger中常用的注解,分别在实体类上、Controller 类上以及 Controller 中的方法上,最后查看 Swagger 如何在页面上呈现在线接口文档的,并且结合 Controller 中的方法在接口中测试一下数据。

4.1 实体类注解

定义 User 实体类,这里主要介绍 Swagger 中的@ApiModel @ApiModelProperty 注解。

@ApiModel(value = "用户实体类")
public class User {
    @ApiModelProperty(value = "用户唯一标识")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;
    // 省略 set 和 get 方法
}

其中@ApiModel 注解用于实体类,表示对类进行说明,用于参数用实体类接收。

@ApiModelProperty 注解用于类中属性,表示对 model 属性的说明或者数据操作更改。

4.2 Controller 类中相关注解
@RestController
@RequestMapping("/swagger")
@Api(value = "Swagger2 在线接口文档")
public class TestController {
    @GetMapping("/get/{id}")
    @ApiOperation(value = "根据用户唯一标识获取用户信息")
    public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
        // 模拟数据库中根据 id 获取 User 信息
        User user = new User(id, "小灰灰", "123456");
        return new JsonResult(user);
    }
}

1、@Api 注解用于类上,表示标识这个类是 swagger 的资源。

2、@ApiOperation 注解用于方法,表示一个 http 请求的操作。

3、@ApiParam 注解用于参数上,用来标明参数信息。

在浏览器中可以看出 Swagger 页面对该接口的信息展示的非常全面,每个注解的作用以及展示的地方注意对应位置,通过页面即可知道该接口的所有信息,那么直接在线测试一下该接口返回的信息,输入 id 为 1,看一下返回数据。

可以看出,直接在页面返回了 json 格式的数据,开发人员可以直接使用该在线接口来测试数据的正确与否,非常方便。

@PostMapping("/insert")
@ApiOperation(value = "添加用户信息")
public JsonResult<Void> insertUser(@RequestBody @ApiParam(value = "用户信息") User user) {
    // 处理添加逻辑
    return new JsonResult<>();
}

重启项目,然后在浏览器中输入 localhost:8080/swagger-ui.html 看效果

5、总结

主要详细分析 Swagger 的优点以及 Spring Boot 集成 Swagger,包括配置,涉及到了实体类和接口类以及如何使用。最后通过页面测试,可以体验 Swagger 的强大之处,基本上是每个项目组中必备的工具之一,所以要掌握该工具的使用。

完整代码实现

1、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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.ma</groupId>
    <artifactId>swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>swagger</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <spring-boot.version>2.6.13</spring-boot.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>tk.mybatis</groupId>
            <artifactId>mapper-spring-boot-starter</artifactId>
            <version>4.2.2</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- 在线文档的支持 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

    </dependencies>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
                <configuration>
                    <mainClass>com.ma.SwaggerApplication</mainClass>
                    <skip>true</skip>
                </configuration>
                <executions>
                    <execution>
                        <id>repackage</id>
                        <goals>
                            <goal>repackage</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

</project>

2、application.properties文件

# 应用服务 WEB 访问端口
server.port=8080

# swagger相关的一个路径匹配规则的配置,如果不进行配置则无法访问到swagger的页面
spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER

3、SwaggerApplication文件:

package com.ma;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

4、创建一个action的包在包内创建HelloController.java文件:

package com.ma.action;

import com.ma.domain.JsonResult;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api(tags="测试控制器")
@RestController
@RequestMapping("/test")
public class HelloController {
    @ApiOperation("问候语测试")
    @GetMapping("/hello")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "username",value = "用户登录账号",required = true),
            @ApiImplicitParam(dataType = "string",name = "password",value = "用户登录密码",required = false,defaultValue = "666666")
    })
    public JsonResult hello(@ApiParam("用户名称") @RequestParam(value="username",required =true) String name){
        String res = "hello" + name + "!";
        return JsonResult.success("处理完毕",res);
    }
}

5、创建一个conf的包在包内创建Swagger3Config.java文件:

package com.ma.conf;

import io.swagger.models.HttpMethod;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@EnableOpenApi
@Configuration
public class Swagger3Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * swagger测试地址:http://localhost:8080/swagger-ui/index.html#/
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 使用Swagger3.0版本
                .enable(true)// 是否关闭在线文档,生产环境关闭
                .apiInfo(apiInfo())  // 指定构建api文档的详细信息的方法
                .select()  // 指定要生成api接口的包路径,这里把action作为包路径,生成controller中的所有接口
                .apis(RequestHandlerSelectors.basePackage("com.ma.action"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))方法接口上添加了ApiOperation注解
                .paths(PathSelectors.any()).build()
                //针对应用的全局响应消息配置
//                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
//                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                ;
    }
    /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档") //设置页面标题
                .description("说明信息")  //设置接口描述
                .contact(new Contact("mayang", "http://baidu.com", "ma@ma.com")) //设置联系方式
                .version("1.0") //设置版本
                .build();  //构建
    }
}

6、创建一个domain的包在包内创建JsonResult.java文件:

package com.ma.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

@Data
@ApiModel("针对前端的响应数据格式规范")
public class JsonResult implements Serializable {
    @ApiModelProperty("是否处理成功,布尔类型数据")
    private Boolean success;
    @ApiModelProperty("响应消息信息,字符串类型")
    private String message;
    @ApiModelProperty("响应数据,对象类型")
    private Object data;

    public static JsonResult success(String message, Object data) {
        JsonResult res=new JsonResult();
        res.setMessage(message);
        res.setSuccess(true);
        res.setData(data);
        return res;
    }
}

7、启动程序后可以通过访问地址http://localhost:8080/swagger-ui/index.html来对swagger网站进行操作

SpringBoot集成 Swagger,spring boot,后端,java文章来源地址https://www.toymoban.com/news/detail-611159.html

到了这里,关于SpringBoot集成 Swagger的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • Spring Cloud Gateway集成聚合型Spring Boot API发布组件knife4j,增强Swagger

    大家都知道,在前后端分离开发的时代,前后端接口对接是一项必不可少的工作。 可是, 作 为后端开发,怎么和前端更好的配合,才能让自己不心累、脑累 ,直接扔给前端一个后端开放api接口文档或者页面,让前端不用看着难受,也不用前端老问你,来愉快的合作呢? 原

    2024年04月22日
    浏览(34)
  • Spring Boot 集成 API 文档 - Swagger、Knife4J、Smart-Doc

    Swagger 作为 API 设计和文档的强大工具,是一个由专门的工具集合支持的框架,它在整个 API 的生命周期中发挥作用,从设计和文档,到测试和部署。通过提供可视化界面,Swagger 让开发人员和最终用户都能清晰地理解和操作 API。 使用建议:笔者建议优先考虑 Knife4J,它已经能

    2024年01月22日
    浏览(56)
  • 【Spring Boot】SpringBoot 优雅整合Swagger Api 自动生成文档

    Swagger 是一套 RESTful API 文档生成工具,可以方便地生成 API 文档并提供 API 调试页面。 而 Spring Boot 是一款非常优秀的 Java Web 开发框架,它可以非常方便地构建 Web 应用程序。 在本文中,我们将介绍如何使用 Swagger 以及如何在 Spring Boot 中整合 Swagger 。 首先,在 pom.xml 文件中添

    2023年04月22日
    浏览(46)
  • spring boot3.x集成swagger出现Type javax.servlet.http.HttpServletRequest not present

    spring boot3.x版本依赖于jakarta依赖包,但是swagger依赖底层应用的javax依赖包,所以只要一启动就会报错。 移除 swagger2依赖 添加 新依赖 @Api(tags = “”) → @Tag(name = “”) @ApiModel(value=“”, description=“”) → @Schema(name=“”, description=“”) @ApiModelProperty(value = “”, required = true) →

    2024年02月09日
    浏览(39)
  • spring boot集成Elasticsearch-SpringBoot(25)

      搜索引擎(search engine )通常意义上是指:根据特定策略,运用特定的爬虫程序从互联网上搜集信息,然后对信息进行处理后,为用户提供检索服务,将检索到的相关信息展示给用户的系统。   而我们讲解的是捜索的索引和检索,不涉及爬虫程序的内容爬取。大部分公司

    2023年04月09日
    浏览(110)
  • 【SpringBoot3】Spring Boot 3.0 集成 Redis 缓存

    Redis缓存是一个开源的使用ANSIC语言编写、支持网络、可基于内存亦可持久化的日志型、Key-Value数据库,并提供多种语言的API。它主要用于作为数据库、缓存和消息中间件,以快速读写和丰富的数据结构支持而著称。 在应用程序和数据库之间,Redis缓存作为一个中间层起着关键

    2024年02月21日
    浏览(52)
  • spring boot学习第六篇:SpringBoot 集成WebSocket详解

    1、WebSocket简介 WebSocket协议是基于TCP的一种新的网络协议。它实现了浏览器与服务器全双工(full-duplex)通信——允许服务器主动发送信息给客户端。 2、为什么需要WebSocket HTTP 是基于请求响应式的,即通信只能由客户端发起,服务端做出响应,无状态,无连接。 无状态:每次连

    2024年01月21日
    浏览(50)
  • SpringBoot + Vue前后端分离项目实战 || 三:Spring Boot后端与Vue前端连接

    系列文章: SpringBoot + Vue前后端分离项目实战 || 一:Vue前端设计 SpringBoot + Vue前后端分离项目实战 || 二:Spring Boot后端与数据库连接 SpringBoot + Vue前后端分离项目实战 || 三:Spring Boot后端与Vue前端连接 SpringBoot + Vue前后端分离项目实战 || 四:用户管理功能实现 SpringBoot + Vue前后

    2024年02月12日
    浏览(66)
  • SpringBoot + Vue前后端分离项目实战 || 二:Spring Boot后端与数据库连接

    系列文章: SpringBoot + Vue前后端分离项目实战 || 一:Vue前端设计 SpringBoot + Vue前后端分离项目实战 || 二:Spring Boot后端与数据库连接 SpringBoot + Vue前后端分离项目实战 || 三:Spring Boot后端与Vue前端连接 SpringBoot + Vue前后端分离项目实战 || 四:用户管理功能实现 SpringBoot + Vue前后

    2024年02月11日
    浏览(60)
  • 后端项目开发:集成接口文档(swagger-ui)

    swagger集成文档具有功能丰富、及时更新、整合简单,内嵌于应用的特点。 由于后台管理和前台接口均需要接口文档,所以在工具包构建BaseSwaggerConfig基类。 1.引入依赖 2.需要添加Swagger配置类。 将需要配置的字段提取出来,单独作为一类 前台接口和后台管理的包的配置,只需

    2024年02月11日
    浏览(37)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包