Swagger接口文档管理工具

news/2024/4/19 16:58:15/

Swagger

  • 1、Swagger
    • 1.1 swagger介绍
    • 1.2 项目集成swagger流程
    • 1.3 项目集成swagger
  • 2、knife4j
    • 2.1 knife4j介绍
    • 2.2 项目集成knife4j

1、Swagger

1.1 swagger介绍

官网:https://swagger.io/

在这里插入图片描述

Swagger 是一个规范和完整的Web API框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

功能主要包含以下几点:

A. 使得前后端分离开发更加方便,有利于团队协作;

B. 接口文档在线自动生成,降低后端开发人员编写接口文档的负担;

C. 接口功能测试;

使用Swagger只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等;

1.2 项目集成swagger流程

  • 引入swagger依赖;
  • 定义swagger配置类;
    • swagger扫描管理的web资源路径;
    • 配置项目文档标题、描述、版本等信息、官网地址等信息;
  • 通过swagger注解给指定资源添加描述信息;
  • 项目启动,访问并测试在线资源;

1.3 项目集成swagger

  • 在 MAVEN构建的项目中引入依赖
    pom.xml

    <!--引入swagger依赖-->
    <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId>
    </dependency>
    <!--swagger ui支持-->
    <!--        导错3.0.0的包导致swagger-ui.html界面显示不出来-->
    <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId>
    </dependency>
    
  • 在项目工程config包定义swagger配置类

     package com.shen.stock.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;/*** 定义swagger配置类*/@Configuration@EnableSwagger2public class SwaggerConfiguration {@Beanpublic Docket buildDocket() {//构建在线API概要对象return new Docket(DocumentationType.SWAGGER_2).select()// 要扫描的API(Controller)基础包.apis(RequestHandlerSelectors.basePackage("com.shen.stock.controller")).paths(PathSelectors.any()).build().apiInfo(buildApiInfo()).enable(true);}private ApiInfo buildApiInfo() {//网站联系方式Contact contact = new Contact("假设在百度","https://www.baidu.com","bhd42414666@163.com");return new ApiInfoBuilder().title("今日指数-在线接口API文档")//文档标题.description("这是一个方便前后端开发人员快速了解开发接口需求的在线接口API文档")//文档描述信息//.contact(contact)//站点联系人相关信息.version("1.0.0")//文档版本.build();}}
    

    在stock_backend工程导入配置类:

      @SpringBootApplication@MapperScan("com.shen.stock.mapper") //扫描持久层的接口统一生成代理对象,并维护到spring的IOC容器中public class BackendApp {public static void main(String[] args) {SpringApplication.run(BackendApp.class, args);}}
    
  • swagger相关注解介绍

    注解位置说明
    @Api加载Controller类上,表示对类的说明
    @ApiModel类(通常是实体类)描述实体类的作用,通常表示接口接收参数的实体对象
    @ApiModelProperty属性描述实体类的属性,(用对象接收参数时,描述对象的一个字段)
    @ApiOperation方法说明方法的用途、作用
    @ApiImplicitParams方法表示一组参数说明
    @ApiImplicitParam方法用在@ApiImplicitParams注解中,指定一个请求参数的各个方面的属性
    @ApiParam方法入参或者方法之上单个参数的描述信息,描述form表单、url参数

    @ApiImplicitParam注解详解:

    属性取值作用
    paramType查询参数类型
    path以地址的形式(rest风格)提交数据
    query直接跟参数完成自动映射赋值(/add/user?name=zhangsan)
    body以流的形式提交 仅支持POST
    header参数在request headers 里边提交
    form以form表单的形式提交 仅支持POST
    dataType参数的数据类型 只作为标志说明,并没有实际验证
    Long
    String
    name接收参数名(方法入参的名称)
    value接收参数的意义描述(描述信息)
    required参数是否必填
    true必填
    false非必填
    defaultValue默认值

其它注解:

@ApiResponse:HTTP响应其中1个描述

@ApiResponses:HTTP响应整体描述

@ApiIgnore:使用该注解忽略这个API

@ApiError :发生错误返回的信息

  • 在项目工程为web资源添加注解支持(示例)
@RestController
@RequestMapping("/api")
@Api(value = "用户认证相关接口定义",tags = "用户功能-用户登录功能")
public class UserController {/*** 注入用户服务bean*/@Autowiredprivate UserService userService;/*** 根据用户名查询用户信息* @param userName* @return*/@GetMapping("/{userName}")@ApiOperation(value = "根据用户名查询用户信息",notes = "用户信息查询",response = SysUser.class)@ApiImplicitParam(paramType = "path",name = "userName",value = "用户名",required = true)public SysUser getUserByUserName(@PathVariable("userName") String userName){return userService.getUserByUserName(userName);}/*** 用户登录功能接口* @param vo* @return*/@PostMapping("/login")@ApiOperation(value = "用户登录功能",notes = "用户登录",response = R.class)public R<LoginRespVo> login(@RequestBody LoginReqVo vo){return userService.login(vo);}/*** 生成登录校验码的访问接口* @return*/@GetMapping("/captcha")@ApiOperation(value = "验证码生成功能",response = R.class)public R<Map> getCaptchaCode(){return userService.getCaptchaCode();}
}
  • 资源访问:http://localhost:8091/swagger-ui.html

在这里插入图片描述

2、knife4j

2.1 knife4j介绍

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

gitee地址:https://gitee.com/xiaoym/knife4j

官方文档:https://doc.xiaominfo.com/

效果演示:http://knife4j.xiaominfo.com/doc.html

核心功能

该UI增强包主要包括两大核心功能:文档说明 和 在线调试

  • 文档说明:根据Swagger的规范说明,详细列出接口文档的说明,包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息,使用 swagger-bootstrap-ui 能根据该文档说明,对该接口的使用情况一目了然。
  • 在线调试:提供在线接口联调的强大功能,自动解析当前接口参数,同时包含表单验证,调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息,帮助开发者在线调试,而不必通过其他测试工具测试接口是否正确,简介、强大。
  • 个性化配置:通过个性化ui配置项,可自定义UI的相关显示信息
  • 离线文档:根据标准规范,生成的在线markdown离线文档,开发者可以进行拷贝生成markdown接口文档,通过其他第三方markdown转换工具转换成html或pdf,这样也可以放弃swagger2markdown组件
  • 接口排序:自1.8.5后,ui支持了接口排序功能,例如一个注册功能主要包含了多个步骤,可以根据swagger-bootstrap-ui提供的接口排序规则实现接口的排序,step化接口操作,方便其他开发者进行接口对接

2.2 项目集成knife4j

1)快速集成knife4j

在 MAVEN 工程添加依赖:
pom.xml

<!--knife4j的依赖-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
<!--支持接口参数校验处理-->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId>
</dependency>

在swagger配置类添加knife4j配置:

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {//.....其它不变......
}

以上有两个注解需要特别说明,如下表:

注解说明
@EnableSwagger2该注解是Springfox-swagger框架提供的使用Swagger注解,该注解必须加
@EnableKnife4j该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,如果你想使用这些增强功能就必须加该注解,否则可以不用加

2)访问在线文档资源:http://localhost:8091/doc.html

在这里插入图片描述


http://www.ppmy.cn/news/1365109.html

相关文章

Day03:Web架构OSS存储负载均衡CDN加速反向代理WAF防护

目录 WAF CDN OSS 反向代理 负载均衡 思维导图 章节知识点&#xff1a; 应用架构&#xff1a;Web/APP/云应用/三方服务/负载均衡等 安全产品&#xff1a;CDN/WAF/IDS/IPS/蜜罐/防火墙/杀毒等 渗透命令&#xff1a;文件上传下载/端口服务/Shell反弹等 抓包技术&#xff1a…

迭代器模式(Iterator Pattern)

定义 迭代器模式&#xff08;Iterator Pattern&#xff09;是一种行为型设计模式&#xff0c;它提供了一种方法来顺序访问聚合对象中的各个元素&#xff0c;而不需要暴露该对象的内部表示。迭代器模式使得客户端代码能够独立于聚合对象的具体实现进行遍历操作。 在迭代器模式…

SD-WAN技术:优化国内外服务器访问的关键

在全球化的商业环境中&#xff0c;企业经常需要在国内访问国外的服务器。然而&#xff0c;由于地理位置和网络架构的限制&#xff0c;这种跨国访问往往会遇到速度慢、延迟高等问题。SD-WAN&#xff08;软件定义广域网&#xff09;技术的兴起&#xff0c;为企业提供了一种新的解…

sql 分割字段,并分行

创建测试表格 CREATE TABLE test (id INT PRIMARY KEY, data VARCHAR(100)); INSERT INTO test VALUES (1, A,B,C); INSERT INTO test VALUES (2, D,E,F,G);查询并分割字段 SELECT id, value AS split_data FROM test CROSS APPLY STRING_SPLIT(data, ,) WHERE LEN(value) …

10:00面试,10:05就出来了,问的问题过于变态了。。。

我从一家小公司转投到另一家公司&#xff0c;期待着新的工作环境和机会。然而&#xff0c;新公司的加班文化让我有些始料未及。虽然薪资相对较高&#xff0c;但长时间的工作和缺乏休息使我身心俱疲。 就在我逐渐适应这种高强度的工作节奏时&#xff0c;公司突然宣布了一则令人…

了解 Go 中原子操作的重要性与使用方法

引言 并发是现代软件开发的一个基本方面&#xff0c;而在 Go 中编写并发程序相对来说是一个相对轻松的任务&#xff0c;这要归功于其强大的并发支持。 Go 提供了对原子操作的内置支持&#xff0c;这在同步并发程序中起着至关重要的作用。在本篇博客文章中&#xff0c;我们将探…

最新红盟云卡个人自动发卡开源系统源码优化版

红盟云卡系统是云商学院旗下的一款基于 PHPMySQL 开发的虚拟商品在线售卖平台。它是一款漂亮且功能丰富的发卡网站&#xff0c;可以与社区进行对接。该系统完全开源且无任何加密&#xff0c;可商业使用&#xff0c;并支持个人免签多个接口。 下载地址&#xff1a;优化版.zip

七、ChatGPT为什么会被热炒?

2023年上半年&#xff0c;ChatGPT引起了广泛的热议&#xff0c;对于ChatGPT有多热&#xff0c;不需要我重复了&#xff0c;你可能在网上看到了很多报道&#xff0c;标题如《ChatGPT揭开AI战幔&#xff1a;杀死黄页一样摧毁Google&#xff1f;》和《ChatGPT强势来袭&#xff0c;…

vscode右键菜单栏功能说明

本文主要介绍在vscode中的python代码文件中&#xff0c;单击鼠标右键出现的菜单栏功能。部分功能可能与安装插件相关&#xff0c;主要用于个人查阅。 单击右键菜单栏如下&#xff1a; GO to xx类型命令 “Go to Definition”、“Go to Declaration”、"Go to Type Defin…

python_pyecharts_柱形图

from pyecharts.charts import Bar from pyecharts import options as opts # 创建一个柱形图实例 bar Bar() # 设置x轴数据 bar.add_xaxis(["A", "B", "C", "D", "E"]) # 设置y轴数据 bar.add_yaxis("柱形图", …

音频smmu问题之smmu学习

一、音频smmu 内存访问问题 在工作中&#xff0c;遇到一个smmu问题&#xff0c;主要log信息如下&#xff1a; arm-smmu 15000000.apps-smmu: Unhandled arm-smmu context fault from soc:spf_core_platform:qcom,msm-audio-ion! arm-smmu 15000000.apps-smmu: FAR 0x0000000…

devc++跑酷小游戏3.5.0

本来想搞存档的&#xff0c;失败了&#xff0c;要再学学文件操作的函数。还有一个打印地图的函数&#xff0c;更失败&#xff0c;彻底放弃。最近开学了&#xff0c;游戏不会经常更新&#xff0c;要写作业。昨天写到10点T_T #include<bits/stdc.h> #include<windows.h…

vue-router4 (二) 引入并配置路由

1.在项目src/router/index.ts 文件夹下配置路由&#xff1a; import { createRouter ,createWebHistory,RouteRecordRaw} from "vue-router"; //1.引入路由//3.routes配置项 const routes:Array<RouteRecordRaw> [{path:"/", //路径name:"…

【GameFramework框架内置模块】4、内置模块之调试器(Debugger)

推荐阅读 CSDN主页GitHub开源地址Unity3D插件分享简书地址QQ群&#xff1a;398291828 大家好&#xff0c;我是佛系工程师☆恬静的小魔龙☆&#xff0c;不定时更新Unity开发技巧&#xff0c;觉得有用记得一键三连哦。 一、前言 【GameFramework框架】系列教程目录&#xff1a;…

Groovy(第八节) Groovy 之类

目录 Song 类 Groovy 类就是 Java 类 类的关系 类初始化 核心的灵活性

如何使用Fastapi上传文件?先从请求体数据讲起

文章目录 1、请求体数据2、form表单数据3、小文件上传1.单文件上传2.多文件上传 4、大文件上传1.单文件上传2.多文件上传 1、请求体数据 前面我们讲到&#xff0c;get请求中&#xff0c;我们将请求数据放在url中&#xff0c;其实是非常不安全的&#xff0c;我们更愿意将请求数…

【MySQL】MySQL复合查询--多表查询自连接子查询 - 副本

文章目录 1.基本查询回顾2.多表查询3.自连接4.子查询 4.1单行子查询4.2多行子查询4.3多列子查询4.4在from子句中使用子查询4.5合并查询 4.5.1 union4.5.2 union all 1.基本查询回顾 表的内容如下&#xff1a; mysql> select * from emp; ----------------------------…

MySQL:单表查询SQL语句

提醒&#xff1a;设定下面的语句是在数据库名为 db_student里执行的。 创建t_student表 CREATE TABLE t_student(id INT NOT NULL AUTO_INCREMENT,stuName VARCHAR(30) DEFAULT NULL,age INT,sex VARCHAR(4) DEFAULT NULL,gradeName VARCHAR(30) DEFAULT NULL,PRIMARY KEY(id)…

修改Qt生成iOS应用的原生底层,编译QtBase下的ios子模块

1.下载Qt源码 2.找到ios.pro子工程 3.使用QtCreaor12打开ios.pro工程 4.出现工程下只有一个.pro文件解决 复制修改好的toolchain.prf文件进行替换. 修改方法:

HTML知识点

HTML 【一】HTML简介 【1】什么是HTML HTML是一种用于创建网页结构和内容的超文本标记语言&#xff0c;它是构建网页的基础。为了让浏览器正确渲染页面&#xff0c;我们必须遵循HTML的语法规则。浏览器在解析网页时会将HTML代码转换为可视化的页面&#xff0c;所以我们在浏览…