【SpringBoot详细教程】-10-SpringBoot整合swagger【持续更新】

news2024/11/25 5:57:15

🌿 Swagger2构建Restful API 文档

🍁 Swagger简介

        由于SpringBoot能够快速开发、便捷部署等特性，相信有很⼤⼀部分SpringBoot的⽤户会⽤来构建

        RESTful API。⽽我们构建RESTfulAPI的⽬的通常都是由于多终端的原因，这些终端会共⽤很多底层 业务逻辑，因此我们会抽象出这样⼀层来同时服务于多个移动端或者Web前端。

        这样⼀来，我们的RESTful API就有可能要⾯对多个开发⼈员或多个开发团队：IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建⼀份 RESTful API⽂档来记录所有接⼝细节，然⽽这样的做法有以下⼏个问题：

  • 由于接⼝众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容 等），⾼质量地创建这份⽂档本身就是件⾮常吃⼒的事，下游的抱怨声不绝于⽿。
  • 随着时间推移，不断修改接⼝实现的时候都必须同步修改接⼝⽂档，⽽⽂档与代码⼜处于两个不同的媒介，除⾮有严格的管理机制，不然很容易导致不⼀致现象。

        为了解决上⾯这样的问题，本⽂将介绍RESTful API的重磅好伙伴Swagger2，它可以轻松的整合到SpringBoot中，并与SpringMVC程序配合组织出强⼤RESTfulAPI⽂档。它既可以减少我们创建⽂档 的⼯作量，同时说明内容⼜整合⼊实现代码中，让维护⽂档和修改代码整合为⼀体，可以让我们在修改代码逻辑的同时⽅便的修改⽂档说明。另外Swagger2也提供了强⼤的⻚⾯测试功能来调试每个RESTful API。

        Swagger 是一系列 RESTful API 的工具，通过 Swagger 可以获得项目的⼀种交互式文档，客户端 SDK 的⾃ 动生成等功能。

使用 Swagger 集成文档具有以下几个优势：

  • 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
  • 及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
  • 整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

在springboot中使用swagger分为两种方式：

  1. 使用springfox的支持
  2. 使用第三方个人（组织）提供的stater

🍁 Springfox方式使用Swagger
  • 在项目中导入依赖：
<!--        swagger依赖：提供注解支持，核心依赖-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<!--        swagger-ui依赖：独立web项目，提供基于浏览器的接口访问界面-->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>
  • 创建Swagger配置类
package com.moxuan.stargym.config;

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.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration // 配置类
public class SwaggerConfig {
	@Bean
	public Docket createRestApi() {
		// DocumentationType.SWAGGER_2 固定的，代表swagger2
		return new Docket(DocumentationType.SWAGGER_2)
				// 如果配置多个文档的时候，那么需要配置groupName来分组标识
				//.groupName("分布式任务系统")
				// 用于生成API信息
				.apiInfo(apiInfo())
				// select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
				.select()
				// 用于指定扫描哪个包下的接口
				.apis(RequestHandlerSelectors.basePackage("com.moxuan.stargym.controller"))
				// 默认选择所有的API,如果你想只为部分API生成文档，可以配置这里
				//.paths(PathSelectors.any())
				.build();
	}

	/**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     * @return
     */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				//  可以用来自定义API的主标题
				.title("健身房管理系统")
				.description("软帝集团信息管理系统，接口地址介绍，包含用户等等信息") // 可以用来描述整体的API
				// .termsOfServiceUrl("") // 用于定义服务的域名
				.version("v1.0") // 可以用来定义版本。
				.license("服务条款")
				.licenseUrl("https://www.softeem.com")
				.contact(new Contact("moxuan","https://www.baidu.com","softeem@163.com"))
				.build(); //
	}
}
  • 在application.yml配置文件中配置对swagger的兼容
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

启动项目，访问：http://localhost:8080/swagger-ui.html

🍁 使用starter方式配置Swagger

对于springboot设计思路来看应该是将所有配置统一在application.yml文件中完成，因此有第三方的依赖提供了swagger的stater支持，具体使用方式如下：

  • 导入依赖
<dependency>
  <groupId>io.github.wilson-he</groupId>
  <artifactId>swagger2-spring-boot-starter</artifactId>
  <version>1.1.2</version>
</dependency>
  • 在application.yml中配置swagger(代替之前的配置类)
# 对swagger的配置
swagger:
  docket:
    # 配置文档扫描的基础包
    base-package: com.moxuan.stargym.controller
    api-info:
      title: 墨轩的健身房管理系统
      description: 这是第一版的快照版，后续持续更新中
      version: v1.1
      license: 接口文档许可
      license-url: http://www.baidu.com
      contact:
        name: moxuan
        url: https://www.baidu.com
        email: moxuan@163.com
  • 添加前一种方式的Spring.mvc配置
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

🌿 常用注解

🍁 @Api & @ApiOperation

@Api: 注解在类(Controller)上，描述当前接口的

  • tags：表示当前接口的标签，支持多个(同一个接口中可能出现多个功能的接口(重复的))

@ApiOperation：注解在方法(Controller类中的方法)上，描述当前方法的使用方式

  • value: 表示对当前接口方法的命名
  • notes: 对当前接口方法的具体描述
@Controller
@Api(tags = {"知识讲解功能测试"})
public class TestController {

    @ApiOperation(value = "测试统一异常处理",notes = "通过人为触发异常，演示统一异常处理")
    @RequestMapping("/hello")
    public String hello()throws Exception{
        throw new Exception("发生错误");
    }

    @ApiOperation(value = "测试MVC环境是否正常",notes = "通过发送请求，检测是否运行正常")
    @RequestMapping("/show")
    @ResponseBody
    public String show(){
        return "go ..........";
    }
}

🍁 @ApiImplicitParams & @ApiImplicitParam

@ApiImplicitParams & @ApiImplicitParam ：用户描述接口中的请求参数

@ApiImplicitParams 里面放的是一个 @ApiImplicitParam 的数组

@ApiImplicitParam 里面的属性包含以下(可选填)

  • name 请求参数名称
  • value 对请求参数名称说明
  • dataTpye 参数类型
  • defaultValue 对默认参数值设定
  • paramType 请求参数类型(如果使用的是Restfull风格的请求路径，则paramType的值为path)
package com.moxuan.stargym.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;

@Api(tags = {"用户功能模块"})
@Controller
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "用户的登录模块",notes = "通过传入的用户名和密码进行登录")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username",value="用户名",dataType = "string",defaultValue = "moxuan"),
            @ApiImplicitParam(name="password",value="密码",dataType = "string",defaultValue = "123456")
    })
    @PostMapping("/loginUser")
    public String loginUser(String username,String password){

        return "index";
    }


    @GetMapping("/{pageNum}/{pageSize}")
    @ApiOperation(value = "用户列表查询",notes = "功能描述：该功能用来实现用户列表查询，包含分页实现，需提供页码数和每页显示条数")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum",value = "页码数",paramType = "path",defaultValue = "1"),
            @ApiImplicitParam(name = "pageSize",value = "每页显示条数",paramType = "path",defaultValue = "2")
    })
    public String getUserList(@PathVariable Integer pageNum, @PathVariable Integer pageSize){

        return "index";
    }
}

🍁 @ApiModel & @ApiModelpropertity

ApiModel & @ApiModelpropertity：用于注解在返回对象或者请求参数为对象中，用户描述对象以及对象中的属性，用在实体类上。

package com.moxuan.stargym.entity;


import com.baomidou.mybatisplus.annotation.TableField;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.sql.Date;
import java.sql.Timestamp;

@Data
@ApiModel(value = "用户对象",description = "一个包含基本信息的用户对象")
public class User {

    @ApiModelProperty(value="用户id")
    private Long id;
    @ApiModelProperty(value = "用户名",required = true)
    private String username;
    @ApiModelProperty(value = "密码",required = true)
    private String password;
    @ApiModelProperty(value = "昵称",required = true)
    private String name;
    @ApiModelProperty(value = "金额",allowEmptyValue = true)
    private Double money;
    @ApiModelProperty(value = "生日")
    private Date birthday;
    @ApiModelProperty(value = "等级")
    private Long level;
    @ApiModelProperty(value = "创建时间")
    @TableField("add_time")
    private Timestamp addTime;
    @ApiModelProperty(value = "性别")
    private String gender;
    @ApiModelProperty(value="电话")
    private String phone;
    @ApiModelProperty(value = "邮箱")
    private String email;
    @ApiModelProperty(value = "邮箱是否认证")
    private Integer isVerify;
}
🍁@ApiParam

@ApiParam 注解用于控制器方法参数中，用于对参数具体解释

@GetMapping("/user/{id}")
@ApiOperation(value = "根据用户id查询用户信息",notes = "功能描述: 提供一个用户的id查询用户信息")
public String getUserById(@ApiParam(name = "uid",value = "用户id",required = true,defaultValue = "2") @PathVariable Integer id){

    return "index";
}
🍁 @ApiResponses & @ApiResponse

@ApiResponses&@ApiResponse：用户接口的返回值信息统一说明，可以用于注解在类(Controller)上和方法上

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

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

相关文章

[Python学习日记-37] Python 中的内置函数（下）

[Python学习日记-37] Python 中的内置函数（下）

简介 在 Python 中有很多内置函数&#xff0c;例如len()&#xff0c;这些函数是Python解释器自带的&#xff0c;可以直接使用。本篇将介绍 O-Z 的内置函数&#xff0c;下图是官方给出的所有 Python 解释器自带的函数 内置函数官方详解&#xff1a;Built-in Functions — Python…
阅读更多...
新160个crackme - 073-abexcrackme3

新160个crackme - 073-abexcrackme3

运行分析 需要破解keyfile PE分析 疑似C程序&#xff0c;32位&#xff0c;EP Section是CODE&#xff0c;猜测无壳 静态分析&动态调试 ida搜索字符串&#xff0c;进入函数 call analysis failed&#xff0c;无法查看伪代码 找到上面提示的地址401088&#xff0c;发现是个Exi…
阅读更多...
鼓组编写：SsdSample鼓映射 GM Map 自动保存 互换midi位置 风格模板 逻辑编辑器

鼓组编写：SsdSample鼓映射 GM Map 自动保存 互换midi位置 风格模板 逻辑编辑器

SsdSample音源的键位映射 方便编写鼓的技巧 可以这样去设置键位关系的面板和钢琴卷帘窗的面板&#xff0c;方便去写鼓。 可以先按GM的midi标准去写鼓&#xff0c;然后比对下鼓的键位映射的关系&#xff0c;去调整鼓。 可以边看自己发b站等处的图文笔记&#xff0c;然后边用电…
阅读更多...
订阅ROS2中相机的相关话题并保存RGB、深度和点云图

订阅ROS2中相机的相关话题并保存RGB、深度和点云图

系统&#xff1a;Ubuntu22.04 ROS2版本&#xff1a;ROS2 humble 1.订阅ROS2中相机的相关话题并保存RGB图、深度图和点云图 ros2 topic list/stellar_1/rgb/image_raw /camera/depth/image_raw /stellar_1/points2CMakeLists.txt cmake_minimum_required(VERSION 3.15) projec…
阅读更多...
Deathnote解题过程

Deathnote解题过程

主机扫描&#xff0c;发现192.168.1.194 arp-scan -l 端口扫描&#xff0c;发现80和22端口 nmap -sS 192.168.1.194 访问80端口发现自动跳转到http://deathnote.vuln/wordpress添加绑定地址就可以访问了 vim /etc/hosts 192.168.1.194 deathnote.vuln 访问发现并没有什么东西…
阅读更多...
IPsec自动方式

IPsec自动方式

文章目录 实验要求实验配置 实验要求 配置 IPsec VPN 采用自动方式同时要满足上网和VPN两种需求使用NAT进行地址映射认证方法和加密算法自行配置采用安全的方法 实验配置 R1&#xff1a; #基本配置 sy sy R1 dhcp enable acl 3001 rule 1 deny ip des 192.168.3.0 0.0.0.255 …
阅读更多...
【Python】解密用户代理：使用 Python User Agents 库探索浏览器和设备信息

【Python】解密用户代理：使用 Python User Agents 库探索浏览器和设备信息

Python User Agents 是一个专为解析 User Agent 字符串而设计的 Python 库。它能够轻松识别访问设备的类型&#xff08;如移动设备、桌面设备或平板&#xff09;&#xff0c;并获取设备、浏览器、操作系统等详细信息。借助它&#xff0c;开发者可以更好地了解访问用户的设备属性…
阅读更多...
SSM人才信息招聘系统-计算机毕业设计源码28084

SSM人才信息招聘系统-计算机毕业设计源码28084

摘要 本研究旨在基于Java和SSM框架设计并实现一个人才信息招聘系统&#xff0c;旨在提升招聘流程的效率和精准度。通过深入研究Java和SSM框架在Web应用开发中的应用&#xff0c;结合人才招聘领域的需求&#xff0c;构建了一个功能完善、稳定高效的招聘系统。利用SSM框架的优势&…
阅读更多...
如何使用ssm实现政务大厅管理系统+vue

如何使用ssm实现政务大厅管理系统+vue

TOC ssm761政务大厅管理系统vue 第一章 课题背景及研究内容 1.1 课题背景 信息数据从传统到当代&#xff0c;是一直在变革当中&#xff0c;突如其来的互联网让传统的信息管理看到了革命性的曙光&#xff0c;因为传统信息管理从时效性&#xff0c;还是安全性&#xff0c;还是…
阅读更多...
Qt QWidget控件

Qt QWidget控件

目录 一、概述 二、Qwidget常用属性及函数介绍 2.1 enable 2.2 geometry 2.3 windowTitle 2.4 windowIcon 2.5 cursor 2.6 font 设置字体样式 2.7 toolTip 2.8 focusPolicy焦点策略 2.9 styleSheet 一、概述 widget翻译而来就是小控件&#xff0c;小部件。…
阅读更多...
Linux shell编程学习笔记85：fold命令——让文件瘦身塑形显示

Linux shell编程学习笔记85：fold命令——让文件瘦身塑形显示

0 引言 我们使用的电脑屏幕有宽有窄&#xff0c;我们有时候希望文件能按照我们的屏幕宽度来调整和匹配&#xff0c;这时我们可以使用fold命令。 1 fold命令 的帮助信息、功能、命令格式、选项和参数说明 1.1 fold 命令 的帮助信息 我们可以输入命令 fold--help 来查看fold …
阅读更多...
Spring Boot实现新闻个性化推荐

Spring Boot实现新闻个性化推荐

1系统概述 1.1 研究背景 如今互联网高速发展&#xff0c;网络遍布全球&#xff0c;通过互联网发布的消息能快而方便的传播到世界每个角落&#xff0c;并且互联网上能传播的信息也很广&#xff0c;比如文字、图片、声音、视频等。从而&#xff0c;这种种好处使得互联网成了信息传…
阅读更多...
大模型训练环境搭建

大模型训练环境搭建

硬件资源说明 本教程基于GPU 3090的服务器 资源类型 型号 核心指标 CPU Intel(R) Xeon(R) Bronze 3204 CPU 1.90GHz 12核 内存 / 125Gi GPU NVIDIA GeForce RTX 3090 24G显存 注意&#xff1a;接下来的部分命令需要使用科学上网&#xff0c;需要事先配置好。 安…
阅读更多...
基于SpringBoot+Vue的摄影社团管理系统

基于SpringBoot+Vue的摄影社团管理系统

作者&#xff1a;计算机学姐 开发技术&#xff1a;SpringBoot、SSM、Vue、MySQL、JSP、ElementUI、Python、小程序等&#xff0c;“文末源码”。 专栏推荐&#xff1a;前后端分离项目源码、SpringBoot项目源码、Vue项目源码、SSM项目源码、微信小程序源码 精品专栏&#xff1a;…
阅读更多...
RK3576部署llama2.c

RK3576部署llama2.c

llama2.c 是一个用纯 C 语言实现的轻量级推理引擎&#xff0c;无需依赖任何第三方库即可高效地进行推理任务。与 llama.cpp 相比&#xff0c;其代码更加直观易懂&#xff0c;并且可以在 PC、嵌入式 Linux 乃至 MCU 上部署。以下是 llama2.c 在 RK3576 开发板上的部署步骤。 工…
阅读更多...
Linux系统安装教程

Linux系统安装教程

Linux安装流程 一、前置准备工作二、开始安装Linux 一、前置准备工作 安装好VMWare虚拟机&#xff0c;并下载Linux系统的安装包&#xff1b; Linux安装包路径为&#xff1a;安装包链接 &#xff0c; 提取码为&#xff1a;4tiM 二、开始安装Linux
阅读更多...
C/C++复习（一）

C/C++复习（一）

1.sizeof 关于sizeof我们是经常使用的&#xff0c;所以使用方法就不需要提及了&#xff0c;这里我们需要注意的是&#xff0c;sizeof 后面如果是表达式可以不用括号&#xff0c;并且sizeof实际上不参与运算&#xff0c;返回的是内容的类型大小&#xff08;size_t类型&#xff0…
阅读更多...
SpringCloud Config配置中心 SpringCloud Bus消息总线

SpringCloud Config配置中心 SpringCloud Bus消息总线

一、SpringCloud Config 使用git储存配置信息 1&#xff09;什么是 SpringCloud Config项目实现的目标是将配置文件从本地项目中抽出来放到git仓库中&#xff0c;项目启动时自动从git仓库中取配置文件。 但是本地项目不直接和git仓库通信&#xff0c;而是通过配置服务器中转。…
阅读更多...
一、经验分享之SaaS标准部署 vs 私有化部署架构图

一、经验分享之SaaS标准部署 vs 私有化部署架构图

SaaS标准部署 vs 私有化部署架构图
阅读更多...
JAVA——IO框架

JAVA——IO框架

目录 一、框架 二、导入框架步骤 三、测试 一、框架 框架就是为了解决某类问题&#xff0c;编写的一套类、接口等。大多数框架都是第三方研发的 好处: 在框架的基础上开发&#xff0c;提高开发效率 框架的形式&#xff1a;一般是把类、接口编译成class形式&#xff0c;再…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023