springboot整合Swagger在线文档

news2024/11/15 21:51:31

SpringBoot整合Swagger2在线文档

一 什么是swagger？

我们前面有讲到说开发时会创建Restful风格的API接口，供第三方或前端人员使用，那么前端人员在使用的过程中怎么知道有哪些接口呢。这个时候可以通过写接口文档来解决，但不同的程序员写出来的可能不一样，前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。如果能有工具帮我们能规范接口文档，最好能自动帮我们生成接口文档就好了。于是生成在线文档的工具就是 swagger就产生了。

1、什么是Swagger ？

Swagger是一款开源工具，依据OpenAPI规范（OpenAPI Specification，简称OAS）可以帮助你设计，构建，生成文档，调用REST APIs。

2、Swagger优点

1.号称世界上最流行的Api框架；

2.RestFul Api 文档在线自动生成工具，Api文档与Api定义同步更新（写完代码文档就实时更新）

3.可以直接运行，可以在线测试Api接口；

4.支持多种语言（java，php等）

二 Springboot中怎么整合Swagger2

Swagger工具既然这么好用，那么我们就来看一下在SpringBoot中怎么整合Swagger。

Swagger的工具很多，但SpringBoot中整合Swagger主要是使用Swagger来构建强大的Restful文档。也就是里面的Swagger UI工具。

这里我们用的版本是Swagger2。

1.创建Springboot项目

选择web、 lombok、 mysql、spring data jpa 依赖 （也可以将spring data jpa 换成mybatis相关依赖）

项目创建成功后在pom文件中添加druid依赖包

完成后pom文件如下：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <!--默认是8.*的版本，根据需要设置自己的版本号-->
        <version>5.1.45</version>
        <scope>runtime</scope>
    </dependency>

    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>druid-spring-boot-starter</artifactId>
        <version>1.1.10</version>
    </dependency>  

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

添加数据库配置信息：

# 数据库的基本配置
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.url=jdbc:mysql://localhost:3306/boot1?characterEncoding=utf8&serverTimezone=GMT%2B8

#配置连接池
spring.datasource.type=com.alibaba.druid.pool.DruidDataSource

# JPA配置
spring.jpa.database=mysql

# 是否在控制台打印SQL
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
# 指定默认的存储引擎为InnoDB，默认情况下，自动创建表的时候会使用 MyISAM 做表的引擎，
# 如果配置了数据库方言为 MySQL57Dialect，则使用 InnoDB 做表的引擎。
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL57Dialect

2.创建Restful风格的Api

​ 结构图如下：

​ 在这里插入图片描述

User类：

package com.example.swagger.pojo;

import io.swagger.annotations.ApiModel;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.persistence.*;


@Data
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "users")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private int id;

    private String uname;

    private int age;

}

UserRepository类：

package com.example.swagger.dao;

import com.example.swagger.pojo.User;
import org.springframework.data.jpa.repository.JpaRepository;



public interface UserRepository  extends JpaRepository<User,Integer> {
}

这里省略了service层，直接在控制层里调用dao层

userController类：

package com.example.swagger.controller;

import com.example.swagger.dao.UserRepository;
import com.example.swagger.pojo.User;
import com.example.swagger.util.Response;
import com.example.swagger.util.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
@RestController
public class UserController {

    @Autowired
    private UserRepository userRepository;

    //查询所有
    @GetMapping("/users")
    public ResponseResult<List<User>> selectUsers()
    {
         List<User> usersList= userRepository.findAll();

         return Response.createOkResp(usersList);
    }

    //根据id查询
    @GetMapping("/users/{id}")
    public ResponseResult<User> selectUserById(@PathVariable(name = "id") int id)
    {
         User user= userRepository.findById(id).get();

         return Response.createOkResp(user);
    }

    //添加
    @PostMapping("/users")
    public ResponseResult addUser(User user)
    {
        userRepository.save(user);

        return Response.createOkResp("add success");
    }
}

3.添加Swagger2

3.1添加相关jar包

<!--   swagger 核心依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--   swagger ui 依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.2 开启Swagger

swagger2 在springboot框架中使用需要 开启 @EnableSwagger2， 同时它支持自定义ui页面的一些信息

在这里插入图片描述

3.3 查看在线文档页

设置上面两个步骤后，打开 http://localhost:8080/swagger-ui.html

就可以看到接口信息

在这里插入图片描述

3.4 配置 Docket（可选）

我们把一个Docket类的一个实例添加到Spring的 BeanFactory中，以实现Swagger页面一些展示信息的定制化，例如作者，标题，描述等信息，也可以进行一些响应的配置项，例如扫描的Controller类基础包名等等。
swagger会在初始化时从Spring的 BeanFactory中获取该实例(如果没有则使用默认的Docket实例)，
来完成初始化。

在这里插入图片描述

package com.example.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


@Configuration
public class Swagger2 {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(
                new ApiInfoBuilder()
                        .contact(new Contact("daimenglaoshi", "", "2398779723@qq.com"))
                        .title("SpringBoot整合Swagger2")
                        .build()
        );
    }
}

上面是对Docket进行一个非常简单的配置。效果如图

在这里插入图片描述

3.5 给Api接口添加注解

package com.example.swagger.controller;

import com.example.swagger.dao.UserRepository;
import com.example.swagger.pojo.User;
import com.example.swagger.util.Response;
import com.example.swagger.util.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
@RestController
@Api(tags = "用户管理相关接口")
public class UserController {

    @Autowired
    private UserRepository userRepository;

    //查询所有
    @GetMapping("/users")
    @ApiOperation("查询所有用户的接口")
    public ResponseResult<List<User>> selectUsers()
    {
         List<User> usersList= userRepository.findAll();

         return Response.createOkResp(usersList);
    }

    //根据id查询
    @GetMapping("/users/{id}")
    @ApiOperation("根据id查询用户的接口")
    @ApiImplicitParam(name = "id", value = "用户id", required = true)
    public ResponseResult<User> selectUserById(@PathVariable(name = "id") int id)
    {
         User user= userRepository.findById(id).get();

         return Response.createOkResp(user);
    }

    //添加
    @PostMapping("/users")
    @ApiOperation("添加用户")
    public ResponseResult addUser(User user)
    {
        userRepository.save(user);

        return Response.createOkResp("add success");
    }
}

这里边使用到了多个注解：
@Api注解： 用来标记当前 Controller 的功能。
@ApiOperation注解：用来标记一个方法的作用。
@ApiImplicitParam注解：用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
需要注意的是，@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger2 框架内必填，抛弃了 Swagger2 ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略。

3.6 参数是对象时

如果参数是一个对象（例如上文的添加接口），对于参数的描述也可以放在实体类中。

package com.example.swagger.pojo;

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

import javax.persistence.*;


@Data
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "users")
@ApiModel(description = "用户字段")
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @ApiModelProperty(value = "用户id", name = "id",  example = "1")
    private int id;

    @ApiModelProperty(value = "用户名", name = "uname", required = true, example = "daimenglaoshi")
    private String uname;

    @ApiModelProperty(value = "年龄", name = "age",  example = "18")
    private int age;

}

3.7 查看接口文档

http://localhost:8080/swagger-ui.html

在这里插入图片描述

·

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

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

相关文章

202/12/10 基础算法每日5道详解

202/12/10 基础算法每日5道详解

21. Merge Two Sorted Lists合并两个排序列表 You are given the heads of two sorted linked lists list1 and list2. Merge the two lists in a one sorted list. The list should be made by splicing together the nodes of the first two lists. Return the head of the m…
阅读更多...
Java基于springboot的人职匹配推荐系统-计算机毕业设计

Java基于springboot的人职匹配推荐系统-计算机毕业设计

项目介绍 随着科学技术的飞速发展&#xff0c;各行各业都在努力与现代先进技术接轨&#xff0c;通过科技手段提高自身的优势&#xff1b;对于人职匹配推荐系统当然也不能排除在外&#xff0c;随着网络技术的不断成熟&#xff0c;带动了人职匹配推荐系统&#xff0c;它彻底改变…
阅读更多...
[附源码]计算机毕业设计基于人脸识别的社区防疫管理系统Springboot程序

[附源码]计算机毕业设计基于人脸识别的社区防疫管理系统Springboot程序

项目运行 环境配置&#xff1a; Jdk1.8 Tomcat7.0 Mysql HBuilderX&#xff08;Webstorm也行&#xff09; Eclispe&#xff08;IntelliJ IDEA,Eclispe,MyEclispe,Sts都支持&#xff09;。 项目技术&#xff1a; SSM mybatis Maven Vue 等等组成&#xff0c;B/S模式 M…
阅读更多...
字节管理薪资被应届生倒挂7K，这真的是不把老员工当人？

字节管理薪资被应届生倒挂7K，这真的是不把老员工当人？

一位字节跳动的小管理爆出&#xff0c;无意中看到了整个部门薪资&#xff0c;本以为自己算比较高的&#xff0c;但看完之后整个人都傻眼了。小组长的职位月薪28K&#xff0c;而手下组员却是35K&#xff0c;当天晚上抽了一包烟也没想明白是为什么。 楼主表示&#xff0c;自己是字…
阅读更多...
算法基础篇-05-排序-LowB三人组(冒泡/选择/插入排序)

算法基础篇-05-排序-LowB三人组(冒泡/选择/插入排序)

1. LowB 三人组介绍 LowB 三人组的时间复杂度都是 O(n^2) 1.1 冒泡排序(Bubble Sort) 列表每2个相邻的数&#xff0c;如果前面比后面大&#xff0c;则交换这两个数。一趟排序完成后&#xff0c;则无序区减少一个数&#xff0c;有序区增加一个数&#xff1b;时间复杂度 O(n^2…
阅读更多...
Linux 伙伴系统

Linux 伙伴系统

Linux 伙伴系统前言一、rmqueue1.1 流程图1.2 函数原型1.3 通过PCP分配1.4 大阶页面分配二、__rmqueue2.1 流程图三、__rmqueue_pcplist3.1 流程图四、__rmqueue_fallback五、__rmqueue_smallest5.1 源码5.1.1 get_page_from_free_area5.1.2 del_page_from_free_list5.1.3 expe…
阅读更多...
从零开始把 SpringBoot 搬到 K8s 上运行，我用了这几步！

从零开始把 SpringBoot 搬到 K8s 上运行，我用了这几步！

前言 大家好&#xff0c;我是网管。咱们的 K8s 入门和实践&#xff0c;在经历了三篇理论知识的后&#xff0c;相信各位都已经期待许久&#xff08;可能的吧&#xff09;&#xff0c;就差私信我&#xff0c;你整着理论整半天有啥用&#xff0c;本大人写的程序怎么能放到 K8s 上运…
阅读更多...
Istio初探

Istio初探

Istio初探 前置环境&#xff1a;docker 一、安装k8s&#xff1a; ● https://segmentfault.com/a/1190000042204035 1、 https://github.com/gotok8s/k8s-docker-desktop-for-mac.git 2、 https://github.com/kubernetes/dashboard 3、 获取token curl ‘http://127.0.0.1:80…
阅读更多...
SpringBoot实战项目杂货铺主页统计图表（折线图、饼状图、条形图）

SpringBoot实战项目杂货铺主页统计图表（折线图、饼状图、条形图）

统计图表的制作我们用到了Echarts&#xff0c;不得不说Echarts真的是百度的超级良心产品了。打Call!!!&#x1f44d;&#x1f44d;&#x1f44d; ✔小插曲&#xff1a; 这里博主顺带提一下&#xff0c;像处理访问量等等数据的时候&#xff0c;往往会涉及到一个并发问题。举个…
阅读更多...
ADI Blackfin DSP处理器-BF533的开发详解27：扩展IO输出的详细讲解（含源代码）

ADI Blackfin DSP处理器-BF533的开发详解27：扩展IO输出的详细讲解（含源代码）

硬件准备 ADSP-EDU-BF533&#xff1a;BF533开发板 AD-HP530ICE&#xff1a;ADI DSP仿真器 软件准备 Visual DSP软件 硬件链接 硬件设计原理图 功能介绍 ADSP-EDU-BF53x 开发板上扩展接口的 PPORT3 中引出了 4 个扩展 IO 接口输出接口&#xff0c;这些连接到了 CPLD&#x…
阅读更多...
【大数据入门核心技术-Hadoop】（八）Hadoop基本管理命令行

【大数据入门核心技术-Hadoop】（八）Hadoop基本管理命令行

目录 一、 三种shell命令方式 二、常见Shell操作命令 三、dfs管理命令行 1、当前haoop环境变量 2、当前集群节点信息 3、运行HTTPFS服务器 4、高可用节点管理 5、单独启动某个节点服务 四、更多命令 一、 三种shell命令方式 HDFS有三种shell命令方式 hadoop fs&#…
阅读更多...
flink部署-1.14

flink部署-1.14

1. 版本说明 本文档内容基于 flink-1.14.x&#xff0c;其他版本的整理&#xff0c;请查看本人博客的 flink 专栏其他文章。 2. 概述 Flink 是一种通用性框架&#xff0c;支持多种不同的部署方式。 本章简要介绍 Flink 集群的组成部分、用途和可用实现。如果你只是想在本地启…
阅读更多...
线程死锁、锁死、饥饿、活锁讲解

线程死锁、锁死、饥饿、活锁讲解

文章目录死锁哲学家就餐问题死锁的检测方式死锁的产生条件死锁的规避死锁的恢复锁死信号丢失锁死嵌套监视器锁死线程饥饿活锁死锁 概念 如果两个或者更多的线程因为相互等待对方而被永远暂停&#xff0c;线程的生命周期变成了BLOCKED或者WAITING&#xff0c;则我们称这些线程产…
阅读更多...
计算机-校验码

计算机-校验码

码距:就单个编码A:00而言&#xff0c;其码距为1&#xff0c;因为其只需要改变一位就变成另一个编码。在两个编码中&#xff0c;从A码到B码转换所需要改变的位数称为码距&#xff0c;如A:00要转换为B:11&#xff0c;码距为2。一般来说&#xff0c;码距越大&#xff0c;越利于纠错…
阅读更多...
基于C++实现（控制台）仓库管理系统【100010021】

基于C++实现（控制台）仓库管理系统【100010021】

1题目与要求 1.1问题描述 某电子公司仓库中有若干批次的同一种电脑&#xff0c;按价格、数量来存储。要求实现功能: 初始化 n 批不同价格电脑入库&#xff1b;出库&#xff1a;销售 m 台价格为 p 的电脑&#xff1b;入库&#xff1a;新到 m 台价格为 p 的电脑&#xff1b;盘…
阅读更多...
Burp Suite Professional 22.11.4 Crack

Burp Suite Professional 22.11.4 Crack

Burp Suite Professional 是网络安全测试人员的首选工具包。使用它来自动执行重复的测试任务 - 然后使用其专家设计的手动和半自动安全测试工具进行更深入的挖掘。Burp Suite Professional 可以帮助您测试 OWASP Top 10 漏洞 Burp Suite 被描述为通过 Port Swigger 提供给用户…
阅读更多...
Python学习基础笔记三十七——collections模块

Python学习基础笔记三十七——collections模块

1、collections模块&#xff1a; 内置数据类型&#xff1a;列表list、字典dict、集合set、元组tuple。 Collections模块提供了另外的数据类型&#xff1a; 队列deque、双端队列&#xff1a;可以快速地从另外一侧追加和推出元素&#xff1b; namedtuple&#xff1a; 生成可以…
阅读更多...
游戏开发53课 阴影

游戏开发53课 阴影

4.8 阴影 阴影的实现方式有很多种&#xff0c;消耗和效果各异。 4.8.1 贴图阴影 贴图的方式最简单&#xff0c;做法是制作一张阴影纹理&#xff0c;放到物体脚下&#xff08;下图&#xff09;&#xff0c;跟随物体一起运动。 贴图阴影渲染非常简单&#xff0c;只需要两个三角…
阅读更多...
智能聊天机器人技术研究与应用

智能聊天机器人技术研究与应用

文章大纲 1. 聊天机器人简介聊天机器人进化历史聊天机器人核心技术2. 预训练模型与聊天机器人研究进展transfomer 架构回顾预训练对话模型3. 知识图谱与智能问答4. 智能聊天机器人应用实践5. 总结与展望正确使用chatGPT“高端的食材往往只需要最朴素的烹饪方式”参考文献与学习…
阅读更多...
OpenFeign使用

OpenFeign使用

OpenFeign使用 在微服务的架构中&#xff0c;传统的http客户端如Httpclient Okhttp HttpURLConnection RestTemplate WebClient 显然不适合。毕竟需要动态的获取服务地址&#xff0c;和进行负载均衡调用。 RPC框架 PC 全称是 Remote Procedure Call &#xff0c;即远程过程调…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023