当前位置: 首页 > news >正文

SpringBoot——Swagger2 接口规范

优质博文:IT-BLOG-CN

如今,REST和微服务已经有了很大的发展势头。但是,REST规范中并没有提供一种规范来编写我们的对外REST接口API文档。每个人都在用自己的方式记录api文档,因此没有一种标准规范能够让我们很容易的理解和使用该接口。我们需要一个共同的规范和统一的工具来解决文档的难易理解文档的混乱格式。Swagger(在谷歌、IBM、微软等公司的支持下)做了一个公共的文档风格来填补上述问题。在本博客中,我们将会学习怎么使用SwaggerSwagger2注解去生成REST API文档。

Swagger(现在是“开放 API计划”)是一种规范和框架,它使用一种人人都能理解的通用语言来描述REST API。还有其他一些可用的框架,比如RAML、求和等等,但是 Swagger是最受欢迎的。它提供了人类可读和机器可读的文档格式。它提供了JSONUI支持。JSON可以用作机器可读的格式,而 Swagger-UI是用于可视化的,通过浏览api文档,人们很容易理解它。

一、添加 Swagger2 的 maven依赖

打开项目中的 pom.xml文件,添加以下两个 swagger依赖。springfox-swagger2 、springfox-swagger-ui。

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.6.1</version>
</dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.6.1</version>
</dependency>

实际上,Swagger的 API有两种类型,并在不同的工件中维护。今天我们将使用 springfox,因为这个版本可以很好地适应任何基于 spring的配置。我们还可以很容易地尝试其他配置,这应该提供相同的功能——配置中没有任何变化。

二、添加 Swagger2配置

使用 Java config的方式添加配置。为了帮助你理解这个配置,我在代码中写了相关的注释:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import com.google.common.base.Predicates;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter
{@Beanpublic Docket api() {// @formatter:off//将控制器注册到 swagger//还配置了Swagger 容器return new Docket(DocumentationType.SWAGGER_2).select().apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any())//扫描 controller所有包.apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot"))).paths(PathSelectors.any()).paths(PathSelectors.ant("/swagger2-demo")).build();// @formatter:on}@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry){//为可视化文档启用swagger ui部件registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

通过 api()方法返回 Docket,调用以下方法:
【1】apiInfo()方法中可以添加 api文档的基本信息(具体类型查看文档);
【2】select()方法返回 ApiSelectorBuilder实例,用于过滤哪些 api需要显示;
【3】apis()方法中填写项目中 Controller类存放的路径;

最后 build()建立 Docket。

三、验证 Swagger2的 JSON格式文档

在application.yml中配置服务名为:swagger2-demo

server.contextPath=/swagger2-demo

maven构建并启动服务器。打开链接,会生成一个JSON格式的文档。这并不是那么容易理解,实际上Swagger已经提供该文档在其他第三方工具中使用,例如当今流行的 API管理工具,它提供了API网关、API缓存、API文档等功能。

四、验证 Swagger2 UI文档

打开链接 在浏览器中来查看Swagger UI文档;

五、Swagger2 注解的使用

默认生成的 API文档很好,但是它们缺乏详细的 API级别信息。Swagger提供了一些注释,可以将这些详细信息添加到 api中。如。@Api我们可以添加这个注解在 Controller上,去添加一个基本的 Controller说明。

@Api(value = "Swagger2DemoRestController", description = "REST APIs related to Student Entity!!!!")
@RestController
public class Swagger2DemoRestController {//...
}

@ApiOperation and @ApiResponses我们添加这个注解到任何 Controller的 rest方法上来给方法添加基本的描述。例如:

@ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")
@ApiResponses(value = {@ApiResponse(code = 200, message = "Success|OK"),@ApiResponse(code = 401, message = "not authorized!"),@ApiResponse(code = 403, message = "forbidden!!!"),@ApiResponse(code = 404, message = "not found!!!") })@RequestMapping(value = "/getStudents")
public List<Student> getStudents() {return students;
}

在这里,我们可以向方法中添加标签,来在 swagger-ui中添加一些分组。@ApiModelProperty这个注解用来在数据模型对象中的属性上添加一些描述,会在 Swagger UI中展示模型的属性。例如:

@ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")
private String name;

Controller 和 Model 类添加了swagger2注解之后,代码清单:Swagger2DemoRestController.java

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.example.springbootswagger2.model.Student;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;@Api(value = "Swagger2DemoRestController", description = "REST Apis related to Student Entity!!!!")
@RestController
public class Swagger2DemoRestController {List<Student> students = new ArrayList<Student>();{students.add(new Student("Sajal", "IV", "India"));students.add(new Student("Lokesh", "V", "India"));students.add(new Student("Kajal", "III", "USA"));students.add(new Student("Sukesh", "VI", "USA"));}@ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")@ApiResponses(value = {@ApiResponse(code = 200, message = "Suceess|OK"),@ApiResponse(code = 401, message = "not authorized!"),@ApiResponse(code = 403, message = "forbidden!!!"),@ApiResponse(code = 404, message = "not found!!!") })@RequestMapping(value = "/getStudents")public List<Student> getStudents() {return students;}@ApiOperation(value = "Get specific Student in the System ", response = Student.class, tags = "getStudent")@RequestMapping(value = "/getStudent/{name}")public Student getStudent(@PathVariable(value = "name") String name) {return students.stream().filter(x -> x.getName().equalsIgnoreCase(name)).collect(Collectors.toList()).get(0);}@ApiOperation(value = "Get specific Student By Country in the System ", response = Student.class, tags = "getStudentByCountry")@RequestMapping(value = "/getStudentByCountry/{country}")public List<Student> getStudentByCountry(@PathVariable(value = "country") String country) {System.out.println("Searching Student in country : " + country);List<Student> studentsByCountry = students.stream().filter(x -> x.getCountry().equalsIgnoreCase(country)).collect(Collectors.toList());System.out.println(studentsByCountry);return studentsByCountry;}// @ApiOperation(value = "Get specific Student By Class in the System ",response = Student.class,tags="getStudentByClass")@RequestMapping(value = "/getStudentByClass/{cls}")public List<Student> getStudentByClass(@PathVariable(value = "cls") String cls) {return students.stream().filter(x -> x.getCls().equalsIgnoreCase(cls)).collect(Collectors.toList());}
}

Student.java 实体类

import io.swagger.annotations.ApiModelProperty;public class Student
{@ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")private String name;@ApiModelProperty(notes = "Class of the Student",name="cls",required=true,value="test class")private String cls;@ApiModelProperty(notes = "Country of the Student",name="country",required=true,value="test country")private String country;public Student(String name, String cls, String country) {super();this.name = name;this.cls = cls;this.country = country;}public String getName() {return name;}public String getCls() {return cls;}public String getCountry() {return country;}@Overridepublic String toString() {return "Student [name=" + name + ", cls=" + cls + ", country=" + country + "]";}
}

六、swagger-ui 展示

现在,当我们的 REST api得到适当的注释时,让我们看看最终的输出。打开http://localhost:8080/swagger2-demo/swagger-ui。在浏览器中查看 Swagger ui文档。

相关文章:

SpringBoot——Swagger2 接口规范

优质博文&#xff1a;IT-BLOG-CN 如今&#xff0c;REST和微服务已经有了很大的发展势头。但是&#xff0c;REST规范中并没有提供一种规范来编写我们的对外REST接口API文档。每个人都在用自己的方式记录api文档&#xff0c;因此没有一种标准规范能够让我们很容易的理解和使用该…...

网络入门---网络编程预备知识

目录标题 ifconfigip地址和mac地址的区别端口号pid和端口号UDP和TCP的初步了解网络字节序socket套接字 ifconfig 通过指令ifconfig便可以查看到两个网络接口&#xff1a; 我们当前使用的是一个linux服务器并是一个终端设备&#xff0c;所以他只需要一个接口用来入网即可&…...

记录一次YAMLException异常

记录一次YAMLException异常 ✅作者简介&#xff1a;大家好&#xff0c;我是Leo&#xff0c;热爱Java后端开发者&#xff0c;一个想要与大家共同进步的男人&#x1f609;&#x1f609; &#x1f34e;个人主页&#xff1a;Leo的博客 &#x1f49e;当前专栏&#xff1a; 报错以及B…...

calendar --- 日历相关函数

calendar --- 日历相关函数 源代码&#xff1a; Lib/calendar.py 这个模块让你可以输出像 Unix cal 那样的日历&#xff0c;它还提供了其它与日历相关的实用函数。 默认情况下&#xff0c;这些日历把星期一作为一周的第一天&#xff0c;星期天作为一周的最后一天&#xff08;这…...

中国信息通信研究院产业与规划研究所校招一面、二面内容

本文介绍2024届秋招中&#xff0c;中国信息通信研究院的数字孪生智慧城市研究员岗位一面、二面的面试基本情况、提问问题等。 10月投递了中国信息通信研究院的数字孪生智慧城市研究员岗位&#xff0c;所在部门为数字孪生与城市数字化研究部。目前完成了一面与二面&#xff0c;在…...

一些数据库学习的小结

一些数据库学习的小结&#xff1a; SQL: 遵循ACID原则。支持Transaction。适合在线交易处理(OLTP)&#xff0c;不适合在线分析处理(OLAP)。例子有 MySQL 读写效率 单机约1KQPS POSTGRESQL NoSQL: 遵循BASE原则。不支持Transaction。例子有 DynamoDB - Amazon Key-Value BigTa…...

【计算机网络】虚拟路由冗余(VRRP)协议原理与配置

目录 1、VRRP虚拟路由器冗余协议 1.1、协议作用 1.2、名词解释 1.3、简介 1.4、工作原理 1.5、应用实例 2、 VRRP配置 2.1、配置命令 1、VRRP虚拟路由器冗余协议 1.1、协议作用 虚拟路由冗余协议(Virtual Router Redundancy Protocol&#xff0c;简称VRRP)是由IETF…...

Using Set Processing Examples 使用集合处理示例

Using Set Processing Examples 使用集合处理示例 Each of the following topics contains an example of set processing. 以下每个主题都包含一个集处理示例。 Payroll 工资单 In this example, suppose the payroll department needs to give a 1000 USD salary increase to…...

Spark将execl表格文件导入到mysql中

实现代码 excel所需的pom依赖 案例实现 实现代码 package excel_mysqlimport org.apache.spark.sql.SparkSession import java.util.Propertiesobject t1 {def main(args: Array[String]): Unit {val spark SparkSession.builder().appName("ExcelToMySQL") /…...

Vue3-Eslint配置代码风格

prettier风格配置 官网&#xff1a;https://prettier.io Eslint&#xff1a;代码纠错&#xff0c;关注于规范 prettier&#xff1a;专注于代码格式化的插件&#xff0c;让代码更加美观 两者各有所长&#xff0c;配合使用优化代码 生效前提&#xff1a; 1&#xff09;禁用…...

“Install Js dependencies failed“JS SDK安装失败【Bug已解决-鸿蒙开发】

文章目录 项目场景:问题描述原因分析:解决方案:解决措施1解决方案2:其他解决方案解决方案3:此Bug解决方案总结项目场景: 在下载JS SDK时,出现下载失败的情况,并显示“Install Js dependencies failed”。 在使用版本为DevEco Studio 3.0.0.601 Beta1进行低代码开发时…...

接口测试入门8问(含答案+文档)

Q1&#xff1a;什么是接口测试&#xff0c;基础知识什么的讲讲吧&#xff01; A&#xff1a;你好&#xff0c;接口可以分下面几种 1、系统与系统之间的调用&#xff0c;比如银行会提供接口供电子商务网站调用&#xff0c;或者说&#xff0c;支付宝会提供接口给淘宝调用 2、上…...

【Spring之事务底层源码解析,持续更新中~~~】

文章目录 一、EnableTransactionManagement工作原理二、Spring事务基本执行原理三、Spring事务传播机制与分类四、Spring事务强制回滚五、TransactionSynchronization六、Spring事务详细执行流程 一、EnableTransactionManagement工作原理 二、Spring事务基本执行原理 三、Sp…...

吃火锅(Python)

题目描述 吃火锅 以上图片来自微信朋友圈&#xff1a;这种天气你有什么破事打电话给我基本没用。但是如果你说“吃火锅”&#xff0c;那就厉害了&#xff0c;我们的故事就开始了。 本题要求你实现一个程序&#xff0c;自动检查你朋友给你发来的信息里有没有 chi1 huo3 guo1。…...

深圳市东星制冷机电受邀莅临2024国际生物发酵展,济南与您相约

深圳市东星制冷机电有限公司受邀莅临2024国际生物发酵展&#xff0c;济南3月5-7日与您相约&#xff01; 展位号&#xff1a;1号馆A53 深圳市东星制冷机电有限公司&#xff0c;&#xff08;东星集团&#xff09;是一家专业生产制冷设备的外商独资大型集团企业,拥有30多年的生产…...

内网渗透(哈希传递)

概念 早期SMB协议明文在网络上传输数据&#xff0c;后来诞生了LM验证机制&#xff0c;LM机制由于过于简单&#xff0c;微软提出了WindowsNT挑战/响应机制&#xff0c;这就是NTLM。 哈希传递前提 同密码(攻击主机与实现主机两台要密码一致)。 NTLM协议 加密ntlm哈希 转换成…...

如何在langchain中对大模型的输出进行格式化

简介 我们知道在大语言模型中, 不管模型的能力有多强大&#xff0c;他的输入和输出基本上都是文本格式的&#xff0c;文本格式的输入输出虽然对人来说非常的友好&#xff0c;但是如果我们想要进行一些结构化处理的话还是会有一点点的不方便。 不用担心&#xff0c;langchain已…...

【送书活动二期】Java和MySQL数据库中关于小数的保存问题

之前总结过一篇文章mysql数据库&#xff1a;decimal类型与decimal长度用法详解&#xff0c;主要是个人学习期间遇到的mysql中关于decimal字段的详解&#xff0c;最近在群里遇到一个小伙伴提出的问题&#xff0c;也有部分涉及&#xff0c;今天就再大致总结一下Java和MySQL数据库…...

11月21日,每日信息差

今天是2023年11月21日&#xff0c;以下是为您准备的16条信息差 第一、国内首条PPP模式市域铁路台州S1线客运量破900万人次。PPP&#xff08;Public-Private Partnership&#xff09;是公共基础设施的一种项目运作模式&#xff0c;指社会资本与政府合作&#xff0c;参与公共基础…...

极速整理文件!Python自动化办公新利器

更多资料获取 &#x1f4da; 个人网站&#xff1a;ipengtao.com 当涉及到自动化办公和文件整理&#xff0c;Python确实是一个强大的工具。在这篇博客文章中&#xff0c;我将深入探讨《极速整理文件&#xff01;Python自动化办公新利器》这个话题&#xff0c;并提供更加丰富和全…...

Linux 文件类型,目录与路径,文件与目录管理

文件类型 后面的字符表示文件类型标志 普通文件&#xff1a;-&#xff08;纯文本文件&#xff0c;二进制文件&#xff0c;数据格式文件&#xff09; 如文本文件、图片、程序文件等。 目录文件&#xff1a;d&#xff08;directory&#xff09; 用来存放其他文件或子目录。 设备…...

基于ASP.NET+ SQL Server实现(Web)医院信息管理系统

医院信息管理系统 1. 课程设计内容 在 visual studio 2017 平台上&#xff0c;开发一个“医院信息管理系统”Web 程序。 2. 课程设计目的 综合运用 c#.net 知识&#xff0c;在 vs 2017 平台上&#xff0c;进行 ASP.NET 应用程序和简易网站的开发&#xff1b;初步熟悉开发一…...

为什么需要建设工程项目管理?工程项目管理有哪些亮点功能?

在建筑行业&#xff0c;项目管理的重要性不言而喻。随着工程规模的扩大、技术复杂度的提升&#xff0c;传统的管理模式已经难以满足现代工程的需求。过去&#xff0c;许多企业依赖手工记录、口头沟通和分散的信息管理&#xff0c;导致效率低下、成本失控、风险频发。例如&#…...

ffmpeg(四):滤镜命令

FFmpeg 的滤镜命令是用于音视频处理中的强大工具&#xff0c;可以完成剪裁、缩放、加水印、调色、合成、旋转、模糊、叠加字幕等复杂的操作。其核心语法格式一般如下&#xff1a; ffmpeg -i input.mp4 -vf "滤镜参数" output.mp4或者带音频滤镜&#xff1a; ffmpeg…...

CocosCreator 之 JavaScript/TypeScript和Java的相互交互

引擎版本&#xff1a; 3.8.1 语言&#xff1a; JavaScript/TypeScript、C、Java 环境&#xff1a;Window 参考&#xff1a;Java原生反射机制 您好&#xff0c;我是鹤九日&#xff01; 回顾 在上篇文章中&#xff1a;CocosCreator Android项目接入UnityAds 广告SDK。 我们简单讲…...

【Oracle】分区表

个人主页&#xff1a;Guiat 归属专栏&#xff1a;Oracle 文章目录 1. 分区表基础概述1.1 分区表的概念与优势1.2 分区类型概览1.3 分区表的工作原理 2. 范围分区 (RANGE Partitioning)2.1 基础范围分区2.1.1 按日期范围分区2.1.2 按数值范围分区 2.2 间隔分区 (INTERVAL Partit…...

Mysql中select查询语句的执行过程

目录 1、介绍 1.1、组件介绍 1.2、Sql执行顺序 2、执行流程 2.1. 连接与认证 2.2. 查询缓存 2.3. 语法解析&#xff08;Parser&#xff09; 2.4、执行sql 1. 预处理&#xff08;Preprocessor&#xff09; 2. 查询优化器&#xff08;Optimizer&#xff09; 3. 执行器…...

python爬虫——气象数据爬取

一、导入库与全局配置 python 运行 import json import datetime import time import requests from sqlalchemy import create_engine import csv import pandas as pd作用&#xff1a; 引入数据解析、网络请求、时间处理、数据库操作等所需库。requests&#xff1a;发送 …...

恶补电源:1.电桥

一、元器件的选择 搜索并选择电桥&#xff0c;再multisim中选择FWB&#xff0c;就有各种型号的电桥: 电桥是用来干嘛的呢&#xff1f; 它是一个由四个二极管搭成的“桥梁”形状的电路&#xff0c;用来把交流电&#xff08;AC&#xff09;变成直流电&#xff08;DC&#xff09;。…...

Selenium 查找页面元素的方式

Selenium 查找页面元素的方式 Selenium 提供了多种方法来查找网页中的元素&#xff0c;以下是主要的定位方式&#xff1a; 基本定位方式 通过ID定位 driver.find_element(By.ID, "element_id")通过Name定位 driver.find_element(By.NAME, "element_name"…...