SpringBoot集成 Swagger

news2024/11/18 1:41:23

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网站进行操作

在这里插入图片描述

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/800078.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

LeetCode647.Palindromic-Substrings<回文子串>

题目&#xff1a; 思路&#xff1a; 错误代码&#xff1a;&#xff08;缺少部分判断&#xff09; 使用的是寻找回文子串的方法。以一个点为中心向两边扫描。但是有一点小问题。 因为回文子串是分奇偶的&#xff0c;所以需要两种判断方式。 看了下答案后发现我的代码距离答案一…

创建一个简单的 Servlet 项目

目录 1.首先创建一个 Maven 项目 2.配置 maven 仓库地址 3.添加引用 4.配置路由文件 web.xml 5.编写简单的代码 6.配置 Tomcat 7.写入名称,点击确定即可 8.访问 1.首先创建一个 Maven 项目 2.配置 maven 仓库地址 3.添加引用 https://mvnrepository.com/ 中央仓库地址…

入门篇——了解数据库

一、数据库是什么&#xff1f; 数据库是存放数据的仓库。它的存储空间很大&#xff0c;可以存放百万条、千万条、上亿条数据。但是数据库并不是随意地将数据进行存放&#xff0c;是有一定的规则的&#xff0c;否则查询的效率会很低。当今世界是一个充满着数据的互联网世界&…

给jupter设置新环境

文章目录 给jupternotebook设置新环境遇到的报错添加路径的方法 给jupternotebook设置新环境 # 先在anaconda界面新建环境 conda env list # 查看conda prompt下的有的环境变量 带星号的是当前活跃的 activate XXXX pip install ipykernel ipython ipython kernel install --u…

AI编程常用工具 Jupyter Notebook

点击上方蓝色字体&#xff0c;选择“设为星标” 回复”云原生“获取基础架构实践 深度学习编程常用工具 我们先来看 4 个常用的编程工具&#xff1a;Sublime Text、Vim、Jupyter。虽然我介绍的是 Jupyter&#xff0c;但并不是要求你必须使用它&#xff0c;你也可以根据自己的喜…

C++中deque的底层讲解

1.前言 1.了解过queue和stack底层的或许了解过&#xff0c;库里面的底层实现&#xff0c;选择的默认容器就是deque&#xff0c;那他有什么好处呢&#xff1f; 2.先前了解过deque的接口会发现&#xff0c;他感觉像是vector和list的合体&#xff0c;什么接口都有&#xff1a; 很…

14.Netty源码之模拟简单的HTTP服务器

highlight: arduino-light 简单的 HTTP 服务器 HTTP 服务器是我们平时最常用的工具之一。同传统 Web 容器 Tomcat、Jetty 一样&#xff0c;Netty 也可以方便地开发一个 HTTP 服务器。我从一个简单的 HTTP 服务器开始&#xff0c;通过程序示例为你展现 Netty 程序如何配置启动&a…

CMU 15-445 -- Logging Schemes - 17

CMU 15-445 -- Logging Schemes - 17 引言IndexFailure ClassificationTransaction FailuresSystem FailuresStorage Media Failures Buffer Pool PoliciesShadow Paging: No-Steal ForceWrite-Ahead Log (WAL): Steal No-ForceLogging SchemesCheckpoints小结 引言 本系列为…

CoTracker跟踪器 - CoTracker: It is Better to Track Together

论文地址&#xff1a;https://arxiv.org/pdf/2307.07635v1.pdf 官方地址&#xff1a;https://co-tracker.github.io/ github地址&#xff1a;https://github.com/facebookresearch/co-tracker/tree/main 引言 在计算机视觉领域&#xff0c;光流估计是历史最久远的问题之一&a…

TCP如何保证服务的可靠性

TCP如何保证服务的可靠性 确认应答超时重传流量控制滑动窗口机制概述发送窗口和接收窗口的工作原理几种滑动窗口协议1比特滑动窗口协议&#xff08;停等协议&#xff09;后退n协议选择重传协议 采用滑动窗口的问题&#xff08;死锁可能&#xff0c;糊涂窗口综合征&#xff09;死…

大数据Flink(五十一):Flink的引入和Flink的简介

文章目录 Flink的引入和Flink的简介 一、Flink的引入 1、第1代——Hadoop MapReduce

60 # http 的基本概念

什么是 HTTP&#xff1f; 通常的网络是在 TCP/IP 协议族的基础上来运作的&#xff0c;HTTP 是一个子集。http 基于 tcp 的协议&#xff0c;在 tcp 的基础上增加了一些规范&#xff0c;就是 header&#xff0c;学习 http 就是学习每个 header 它有什么作用。 TCP/IP 协议族 协…

RN 设置背景图片(使用ImageBackground组件)

在RN版本0.46版本的时候添加了ImageBackground控件。ImageBackground可以设置背景图片&#xff0c;使用方法和image一样&#xff0c;里面嵌套了其他的组件 import React from "react"; import { ImageBackground, StyleSheet, Text, View } from "react-native…

【项目6 UI Demo】前端代码记录

前端代码记录 1.GridListItem中的布局 在这个Item中的布局采用的是VBox和HBox相结合的方式。相关的代码如下&#xff1a; <VBox class"sapUiTinyMargin"><HBox justifyContent"SpaceBetween"><Titletext"{ToolNumber}"wrapping…

C++之lambda表达式/function/using/typedef用法总结(一百六十六)

简介&#xff1a; CSDN博客专家&#xff0c;专注Android/Linux系统&#xff0c;分享多mic语音方案、音视频、编解码等技术&#xff0c;与大家一起成长&#xff01; 优质专栏&#xff1a;Audio工程师进阶系列【原创干货持续更新中……】&#x1f680; 人生格言&#xff1a; 人生…

Linux基础以及常用命令

目录 1 Linux简介1.1 不同应用领域的主流操作系统1.2 Linux系统版本1.3 Linux安装1.3.1 安装VMWare1.3.2 安装CentOS镜像1.3.3 网卡设置1.3.4 安装SSH连接工具1.3.5 Linux和Windows目录结构对比 2 Linux常用命令2.0 常用命令&#xff08;ls&#xff0c;pwd&#xff0c;cd&#…

LinuxC语言-网络通信tcp/ip errno获取错误描述字符串

目录 服务端代码&#xff1a; 获取errno错误码&#xff1a; 客户端代码&#xff1a; 运行结果: 服务端代码&#xff1a; #include <stdio.h> #include<sys/types.h> #include<sys/socket.h> #include<string.h> #include<netinet/in.h> #in…

在Mac上搭建Gradle环境

在Mac上搭建Gradle环境&#xff1a; 步骤1&#xff1a;下载并安装Java开发工具包&#xff08;JDK&#xff09; Gradle运行需要Java开发工具包&#xff08;JDK&#xff09;。您可以从Oracle官网下载适合您的操作系统版本的JDK。请按照以下步骤进行操作&#xff1a; 打开浏览器…

性能提升,SpringBoot 3.2虚拟线程来了

spring boot 3.2 会提供默认支持&#xff0c;必须Java19。 在以往的项目中&#xff0c;我们面临了这样一种情况&#xff1a;我们收到了数千个认证请求。为了确保安全性&#xff0c;我们依靠第三方系统发送短信 OTP 进行验证。然而&#xff0c;有时候第三方系统花费的时间比预期…

MySQL中锁的简介——表级锁-表锁

1.表级锁简介 2.读锁介绍 lock tables score read;3.写锁介绍 lock tables score write;