《Techporters架构搭建》-Day07 集成API文档工具

news2024/11/23 14:44:18

API文档化

  • 前言
  • API文档化历史
  • 集成Knife4j
  • 常用注解
    • 基本信息注解
    • 分组注解
    • 请求方法注解
    • 路径注解
  • 使用示例

源码地址：请看day07

前言

在现代软件开发中，良好的API文档是团队协作和项目管理中不可或缺的一部分。OpenAPI规范（前身为Swagger）为我们提供了一种标准化的方式来描述和管理RESTful API，Spring Boot通过集成相关工具使得生成和维护API文档变得更加简单和高效。本文将详细介绍如何在Spring Boot项目中利用OpenAPI来自动生成和管理API文档。

API文档化历史

做过API文档化经常可以听到一下几个概念：Swagger、SpringFox、SpringDoc、OpenAPI、Knife4j
1.Swagger2是一组围绕 OpenAPI 规范构建的开源工具，可帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：

Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。
Swagger UI – 将 OpenAPI规范呈现为交互式 API 文档。
swagger2于17年停止维护，现在最新的版本为 Swagger3（Open Api3）。

2.Open API
OpenAPI是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被Linux列为api标准，从而成为行业标准，如果想了解
Open API规范，请查看 Swagger Editor 和 OpenAPI规范
3.Swagger3(OpenAPI3)
Swagger 规范已于 2015 年捐赠给 Linux 基金会后改名为 OpenAPI，并定义最新的规范为 OpenAPI 3.0。所以现在的 Swagger 3.0 就是 OpenAPI 3.0。

4.SpringFox与SpringDoc
SpringFox： SpringFox 是一个老牌的库，用于将 Spring Boot 应用程序集成到 Swagger（现在称为 OpenAPI）规范中。它通过使用 Swagger 注解来描述 API，并生成符合 OpenAPI 规范的文档。SpringFox 支持Swagger 2.0 版本以及后续的 OpenAPI 3.0 版本。 SpringFox： 使用 @Api、@ApiOperation 等 Swagger 注解
SpringDoc： SpringDoc是一个相对较新的库，也是用于将 Spring Boot 应用程序集成到 OpenAPI 规范中。它采用更简化的注解，使得在代码中描述 API更为直观。SpringDoc 专注于支持 OpenAPI 3.0 版本。使用 @OpenAPIDefinition、@Operation 等 OpenAPI 注解

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

集成Knife4j

目前只创建了一个微服务，所以本节我们只是在tps-system中添加Knife4j，后续多个微服务后，我们会进行改进，通过网关聚合所有的Swagger微服务文档。
首先，引用Knife4j的starter,在根Gradle下添加版本号及knife4j引入

knife4jVersion='4.4.0'
implementation "com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:${knife4jVersion}"

引入之后，要启用Knife4j的增强功能，可以在配置文件中进行开启，knife4j各种配置可以到官网去看看
部分配置如下:

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.tps.cloud.system
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
  basic:
    enable: true
    # Basic认证用户名
    username: system
    # Basic认证密码
    password: 123456

常用注解

在写代码之前，先了解一下OpenAPI 3.0有哪些注解以及各个注解的作用。

基本信息注解

@OpenAPIDefinition

  • 描述：用于定义整个 API 文档的基本信息。
  • 可用于：类、接口。
  • 属性：
    • info：指定 @Info 注解的对象，用于描述 API 文档的基本信息。

@Info

  • 描述：用于定义 API 文档的基本信息。
  • 可用于：类、接口。
  • 属性：
    • title：API 的标题。
    • description：API 的描述。
    • version：API 的版本号。
    • termsOfService：服务条款的 URL。
    • contact：指定 @Contact 注解的对象，用于描述联系人信息。
    • license：指定 @License 注解的对象，用于描述许可证信息。

@Contact

  • 描述：用于定义 API 文档中的联系人信息。
  • 可用于：类、接口。
  • 属性：
    name：联系人的名称。
    url：联系人的网址。
    email：联系人的电子邮件地址。

@License

  • 描述：用于定义 API 文档中的许可证信息。
  • 可用于：类、接口。
  • 属性：
    • name：许可证的名称。
    • url：许可证的网址。

分组注解

@Tag

  • 描述：用于给 API 分组，用途类似于为 API 文档添加标签。
  • 可用于：方法、类、接口。
  • 属性：
    • name：分组的名称。

请求方法注解

以下注解用于描述 API 的请求方法：

@Operation

  • 描述：用于描述 API 的操作。
  • 可用于：方法。
  • 属性：
    • summary：操作的摘要信息。
    • description：操作的详细描述。
    • tags：指定 @Tag 注解的对象数组，用于将操作归类到特定的分组。
    • parameters：指定 @Parameter 注解的对象数组，用于描述操作的输入参数。
    • responses：指定 @ApiResponse 注解的对象数组，用于描述操作的响应结果。
    • requestBody：指定 @RequestBody 注解的对象，用于描述操作的请求体。

@Parameter

  • 描述：用于描述操作的输入参数。
  • 可用于：方法。
  • 属性：
    • name：参数的名称。
    • in：参数的位置，可以是 path、query、header、cookie 中的一种。
    • description：参数的描述。
    • required：参数是否必需，默认为 false。
    • schema：指定 @Schema 注解的对象，用于描述参数的数据类型。

@RequestBody

  • 描述：用于描述操作的请求体。
  • 可用于：方法。
  • 属性：
    • required：请求体是否必需，默认为 false。
    • content：指定 @Content 注解的对象数组，用于描述请求体的内容。

@ApiResponse

  • 描述：用于描述操作的响应结果。
  • 可用于：方法。
  • 属性：
    • responseCode：响应的状态码。
      -description：响应的描述。
      -content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

  • 描述：用于描述请求体或响应的内容。
  • 可用于：方法。
  • 属性：
    • mediaType：内容的媒体类型。
    • schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

  • 描述：用于描述数据模型的属性。
  • 可用于：方法、类、接口。
  • 属性：
    • title：数据模型的标题。
    • description：数据模型的描述。
    • type：数据模型的类型。
    • format：数据模型的格式。

路径注解

以下注解用于描述 API 的路径：
@Path

  • 描述：用于定义路径参数。
  • 可用于：方法。
  • 属性：
    • value：路径参数的名称。

@PathVariable

  • 描述：用于描述路径参数。
  • 可用于：方法的参数。
  • 属性：
    • value：路径参数的名称。

@RequestParam

  • 描述：用于描述查询参数。
  • 可用于：方法的参数。
  • 属性：
    • value：查询参数的名称。
    • required：查询参数是否必需，默认为 false。

@RequestBody

  • 描述：用于描述请求体。
  • 可用于：方法的参数。

响应注解
以下注解用于描述 API 的响应结果：

@ApiResponse

  • 描述：用于描述响应结果。
  • 可用于：方法。
  • 属性：
    • responseCode：响应的状态码。
    • description：响应的描述。
    • content：指定 @Content 注解的对象数组，用于描述响应的内容。

@Content

  • 描述：用于描述响应结果的内容。
  • 可用于：方法。
  • 属性：
    • mediaType：内容的媒体类型。
    • schema：指定 @Schema 注解的对象，用于描述内容的数据类型。

@Schema

  • 描述：用于描述数据模型的属性。
  • 可用于：方法、类、接口。
  • 属性：
    • title：数据模型的标题。
    • description：数据模型的描述。
    • type：数据模型的类型。
    • format：数据模型的格式。

使用示例

package com.tps.cloud.system.controller;

import com.tps.cloud.group.UpdateGroup;
import com.tps.cloud.response.Result;
import com.tps.cloud.system.dto.SystemUserDto;
import com.tps.cloud.system.service.SystemUserService;
import com.tps.cloud.system.vo.SystemUserVo;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.AllArgsConstructor;
import org.springframework.context.support.MessageSourceAccessor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

/**
 * 用户管理 前端控制器
 */
@RestController
@AllArgsConstructor
@RequestMapping("/system/users")
@Tag(name = "用户管理", description = "用于管理用户信息")
public class SystemUserController {

    private final SystemUserService systemUserService;

    private final MessageSourceAccessor messages;

    @PostMapping
    @Operation(summary = "创建用户", description = "创建用户")
    public Result<Long> save(@RequestBody @Validated SystemUserDto systemUserDto) {
        //验证用户唯一
        SystemUserVo systemUserVo=systemUserService.findByUsername(systemUserDto.getUsername());
        if(systemUserVo!=null){
            return Result.failed(messages.getMessage("SystemUserDto.Username.Exist"));
        }
        Long id=systemUserService.createUser(systemUserDto);
        return Result.ok(id);
    }

    @PutMapping
    @Operation(summary = "更新用户信息", description = "更新用户信息")
    public Result<Boolean> update(@RequestBody @Validated({UpdateGroup.class}) SystemUserDto systemUserDto) {
        systemUserService.updateUser(systemUserDto);
        return Result.ok(true);
    }

    @GetMapping
    @Operation(summary = "根据ID获取用户信息", description = "根据用户ID查询用户的详细信息")
    @Parameter(name = "id", description = "用户id", required = true)
    public Result<SystemUserVo> getUser(@RequestParam("id") Long id) {
        SystemUserVo user = systemUserService.getUser(id);
        return Result.ok(user);
    }
}

package com.tps.cloud.system.dto;

import com.tps.cloud.group.AddGroup;
import com.tps.cloud.group.UpdateGroup;
import com.tps.cloud.system.constraint.UniqueUsername;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 用户信息传输类
 */
@Data
public class SystemUserDto  {
    /**
     * 用户id
     */
    @Schema(description = "用户id")
    private Long id;
    /**
     * 用户账号
     */
    @NotBlank(message = "{SystemUserDto.Username.NotEmpty}")
    //@UniqueUsername
    @Schema(description = "用户账号")
    private String username;
    /**
     * 密码
     */
    @NotBlank(message = "密码不能为空",groups = {AddGroup.class,UpdateGroup.class})
    @Schema(description = "密码")
    private String password;
    /**
     * 用户昵称
     */
    @Schema(description = "用户昵称")
    private String nickname;
    /**
     * 备注
     */
    @Schema(description = "备注")
    private String remark;
    /**
     * 部门id
     */
    @Schema(description = "部门id")
    private Long deptId;
    /**
     * 用户邮箱
     */
    @Schema(description = "用户邮箱")
    private String email;
    /**
     * 手机号码
     */
    @Schema(description = "手机号码")
    private String mobile;
    /**
     * 用户性别
     */
    @Schema(description = "用户性别")
    private Integer sex;
    /**
     * 头像地址
     */
    @Schema(description = "头像地址")
    private String avatar;
    /**
     * 帐号状态（0正常 1停用）
     */
    @Schema(description = "帐号状态")
    private Integer status;
    /**
     * 最后登录IP
     */
    @Schema(description = "最后登录IP")
    private String loginIp;
    /**
     * 最后登录时间
     */
    @Schema(description = "最后登录时间")
    private LocalDateTime loginDate;

    /**
     * 部门
     */
    @Valid
    @Schema(description = "部门")
    private SystemDeptDto systemDept;
}

重新启动项目，访问http://localhost:8080/doc.html
在这里插入图片描述

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

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

相关文章

AI绘画Stable Diffusion插件—LayerDiffusion 分层控图新突破！生成透明图片前后景图片融合，毫无违和感！

AI绘画Stable Diffusion插件—LayerDiffusion 分层控图新突破！生成透明图片前后景图片融合，毫无违和感！

大家好&#xff0c;我是画画的小强 用AI绘画Stable Diffusion 生成透明图片怎么搞&#xff1f; 这要搁之前&#xff0c;我们需要生成完图片&#xff0c;然后放到去背景插件中调整参数去除背景&#xff01;效果一般般 如果想要在一张图片上添加主体&#xff0c;该怎么搞&#…
阅读更多...
使用gpreftools测试性能

使用gpreftools测试性能

参考文献&#xff1a; C 性能分析工具调研_性能分析工具 gperf perf vergi 比较-CSDN博客性能测试工具CPU profiler(gperftools)的使用心得-CSDN博客gperftools使用方法和常见问题_pprof no nodes to print-CSDN博客c 分析 gperftools 总结 | Weakyon Blog 文章目录 安装使用 …
阅读更多...
如何搭建知识库？2024年6款工具优质推荐

如何搭建知识库？2024年6款工具优质推荐

一、引言 在当今信息化时代&#xff0c;知识管理已成为企业提升竞争力和实现持续发展的关键。搭建一个高效、易用的知识库&#xff0c;不仅能帮助企业更好地整合和分享内部资源&#xff0c;还能提升员工的工作效率和创新能力。本文将详细介绍如何搭建知识库&#xff0c;并推荐…
阅读更多...
制作语音数据集: 爬取B站音视频+基于whisper语音识别标注

制作语音数据集: 爬取B站音视频+基于whisper语音识别标注

本文以制作小学课堂音频数据集为例子 1. 搜索关键字获取音视频链接 if __name__ "__main__":with sync_playwright() as playwright:searcher BLVideoSearch(playwright, headlessTrue)url searcher.make_url(keyword["小学公开课"])searcher.run(url, …
阅读更多...
英文科目一外国人要考中国驾照理论考试题目是什么样的

英文科目一外国人要考中国驾照理论考试题目是什么样的

随着中国的国际化发展&#xff0c;越来越多的外国朋友选择在中国生活和工作&#xff0c;其中一些人可能会考虑在这里考取驾驶执照。然而&#xff0c;语言障碍成为了他们面临的一大挑战。一个常见的问题是科目一考试是否提供英文版本或者是否有翻译服务。本文将介绍中国车管所提…
阅读更多...
什么是IP?

什么是IP?

目录 简介 IP IP协议 IP地址 发展历程 IP地址类型 公有地址 私有地址 IP地址编址方式 A类IP地址 B类IP地址 C类IP地址 D类IP地址 特殊的网址 子网 超网 无类间路由 IP地址的分配 IP地址管理 手工管理模式 DHCP分配IP地址的管理模式 通过交换机管理IP 地址…
阅读更多...
分布式ID-一窥雪花算法的原生实现问题与解决方案（CosId）

分布式ID-一窥雪花算法的原生实现问题与解决方案（CosId）

分布式ID-雪花算法的问题与方案&#xff08;CosId&#xff09; 基本原理 外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url%E5%88%86%E5%B8%83%E5%BC%8FID-%E9%9B%AA%E8%8A%B1%E7%AE%9…
阅读更多...
微分方程（Blanchard Differential Equations 4th）中文版Section1.6

微分方程（Blanchard Differential Equations 4th）中文版Section1.6

平衡点与相直线 给定一个微分方程 d y d t = f ( t , y ) , \frac{dy}{dt} = f(t, y), dtdy​=f(t,y), 我们可以通过绘制斜率场和勾勒图形来大致了解解的行为，或者使用欧拉法计算近似解。有时我们甚至可以推导出解的显式公式并绘制结果。所有这些技术都需要相当多的工作，无…
阅读更多...
武汉流星汇聚：西班牙时尚消费高涨，中国商家借亚马逊平台拓商机

武汉流星汇聚：西班牙时尚消费高涨，中国商家借亚马逊平台拓商机

在2024年第二季度的亚马逊西班牙站&#xff0c;一场前所未有的时尚盛宴正悄然上演。销售额同比高增长TOP10品类榜单的揭晓&#xff0c;不仅揭示了西班牙消费者对于时尚品类的狂热追求&#xff0c;更为亚马逊平台上的中国商家开启了一扇通往新蓝海的大门。其中&#xff0c;男士拳…
阅读更多...
使用LlamaIndex中的Reli 进行实体链接和关系提取

使用LlamaIndex中的Reli 进行实体链接和关系提取

从文本中构建知识图谱一直是一个引人入胜的研究领域。随着大型语言模型（LLM）的出现，这一领域获得了更多主流关注。然而，大型语言模型的成本可能相当高昂。另一种方法是对较小的模型进行微调，这种方法得到了学术研究的支持，并产生了更有效的解决方案。今天，我们将探讨罗马…
阅读更多...
redis mysql oracle mssql postgresql提权工具mdut

redis mysql oracle mssql postgresql提权工具mdut

mdut工具使用 mdut用于数据库的连接&#xff0c;连接成功后可用户反弹shell&#xff0c;命令执行 mdut工具运行说明 1&#xff0c;此工具需要在jdk1.8的环境下运行 2&#xff0c;下载完工具包之后&#xff0c;找到java1.8环境&#xff0c;运行jar文件 java.exe -jar Multipl…
阅读更多...
Linux Redis 删除指定库下所有 Key

Linux Redis 删除指定库下所有 Key

代码示例 以下是每一步需要执行的代码及其注释&#xff1a; 连接 Redis redis-cli -h <hostname> -p <port> -a <password>-h&#xff1a;指定 Redis 服务器的主机名。 -p&#xff1a;指定 Redis 服务器的端口号。 -a&#xff1a;指定 Redis 服务器的密码。…
阅读更多...
基于Arch的轻量级发行版Archcraft结合内网穿透实现远程SSH连接

基于Arch的轻量级发行版Archcraft结合内网穿透实现远程SSH连接

文章目录 前言1. 本地SSH连接测试2. Archcraft安装Cpolar3. 配置 SSH公网地址4. 公网远程SSH连接5. 固定SSH公网地址6. SSH固定地址连接 前言 本文主要介绍如何在Archcraft系统中安装Cpolar内网穿透工具,并以实现Windows环境ssh远程连接本地局域网Archcraft系统来说明使用内网…
阅读更多...
ubuntu安装虚拟环境（tensorflow、torch）

ubuntu安装虚拟环境（tensorflow、torch）

一、安装需求 1、确保ubuntu可以ping通百度 2、设置好了pip镜像源&#xff0c;&#xff08;具体可看&#xff1a;ubuntu配pip的源-CSDN博客&#xff09; 二、安装虚拟环境&#xff08;务必使用sudo进行&#xff09; step1&#xff1a;执行安装命令 更改了pip默认使用pip3的…
阅读更多...
SpringBoot+Vue在线商城(电子商城)系统-附源码与配套论文

SpringBoot+Vue在线商城(电子商城)系统-附源码与配套论文

摘 要 随着互联网技术的发展和普及&#xff0c;电子商务在全球范围内得到了迅猛的发展&#xff0c;已经成为了一种重要的商业模式和生活方式。电子商城是电子商务的重要组成部分&#xff0c;是一个基于互联网的商业模式和交易平台&#xff0c;通过网络进行产品和服务的销售。…
阅读更多...
18705 01背包问题

18705 01背包问题

### 分析 这是一个典型的0/1背包问题。我们需要在有限的背包容量下&#xff0c;选择若干物品&#xff0c;使得获得的总价值最大。可以使用动态规划来解决这个问题。 ### 伪代码 1. 定义一个一维数组dp&#xff0c;其中dp[j]表示容量为j的背包能获得的最大价值。 2. 初始化dp[0…
阅读更多...
STM32的相关简单介绍

STM32的相关简单介绍

一、什么是STM32 STM32是ST公司设计的一系列以ARM Cortex-M为核心的32位微控制器 ST公司&#xff0c;即意法半导体集团(STMicrolectronics,简称ST)&#xff0c;1987年成立。由意大利的SGS微电子公司和法国Thomson半导体公司合并而成。 在当下的32位微控制器中&#xff0c;STM…
阅读更多...
系统主机加固的十个方法，教你做好主机加固

系统主机加固的十个方法，教你做好主机加固

环境背景 随着全球数字化转型的加速&#xff0c;企业IT环境变得愈发复杂&#xff0c;服务器主机面临的安全威胁也日益多样化。无论是工业控制系统、企业内部网络、企业内部服务器&#xff0c;还是云计算环境&#xff0c;都可能成为网络攻击的目标。此外&#xff0c;随着“工业…
阅读更多...
重构版：链动3+1创新裂变模式解析

重构版：链动3+1创新裂变模式解析

链动31模式&#xff0c;作为一种创新的市场扩张策略&#xff0c;专注于通过产品的独特魅力驱动用户自主传播与裂变。与传统的链动21模式相比&#xff0c;它在结构上进行了重大革新&#xff0c;不再局限于传统的太阳线裂变方式&#xff0c;而是引入了四四复制的架构&#xff0c;…
阅读更多...
【Python零基础】while循环和用户输入

【Python零基础】while循环和用户输入

文章目录 前言一、input()函数二、while循环三、使用while循环来处理列表和字典总结 前言 我们开发一个应用程序&#xff0c;目的都是为了解决最终用户的问题&#xff0c;针对用户界面输入的数据&#xff0c;按照用户期待的逻辑进行处理&#xff0c;得到用户想要的结果。本章将…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023