SpringDoc和Swagger使用

news/2025/3/29 13:35:35/

目录

一、SpringDoc

1.添加依赖

2.配置代码

配置解释

（1）springdoc.api-docs.path

（2）springdoc.swagger-ui.path

（3）springdoc.swagger-ui.operationsSorter

（4）springdoc.swagger-ui.tagsSorter

（5）springdoc.title

使用

3.控制器处理

4.访问

5.优点

6.缺点

二、swagger

1. 添加依赖项

2. 配置 Swagger

3. 将注释添加到控制器中

4. 访问 Swagger UI

5.优点

6.缺点

Swagger和Springdoc是两个常用的工具，用于生成和维护API文档，特别是针对基于REST的Web服务。它们有效地提升了API的可读性和可维护性，帮助开发者、产品经理和其他利益相关者更好地理解和使用所提供的API。

注意：Swagger支持springboot2.0但不支持springboot3.0

一、SpringDoc

Springdoc是一个开源的库，旨在将Spring Boot项目的RESTful API与OpenAPI 3文档生成器集成。Springdoc与Spring Boot应用无缝集成，并支持包括Swagger UI在内的多种用户界面。

1.添加依赖
    <dependencies><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.6.0</version></dependency></dependencies>
2.配置代码

添加一个配置类，并添加xml配置

配置解释
springdoc:api-docs:path: /v3/api-docsswagger-ui:path: /swagger-ui.htmloperationsSorter: methodtagsSorter: alpha
（1）springdoc.api-docs.path

  • 属性路径:springdoc.api-docs.path

  • 作用: 定义 OpenAPI 文档的访问路径。

  • 默认值:/v3/api-docs

  • 示例:

    springdoc:api-docs:path: /v3/api-docs

    配置后，API 文档可以通过http://<host>:<port>/v3/api-docs访问。

（2）springdoc.swagger-ui.path

  • 属性路径:springdoc.swagger-ui.path

  • 作用: 定义 Swagger UI 的访问路径。

  • 默认值:/swagger-ui.html

  • 示例:

    springdoc:swagger-ui:path: /swagger-ui.html

    配置后，Swagger UI 可以通过http://<host>:<port>/swagger-ui.html访问。

（3）springdoc.swagger-ui.operationsSorter

  • 属性路径:springdoc.swagger-ui.operationsSorter

  • 作用: 定义如何对 Swagger UI 中的操作进行排序。

  • 可选值:

    • alpha: 按照操作名称的字母顺序排列。
    • method: 按照 HTTP 方法进行排序（如 GET, POST, PUT, DELETE）。

  • 示例:

    springdoc:swagger-ui:operationsSorter: method

    配置后，操作会按照 HTTP 方法的顺序显示。

（4）springdoc.swagger-ui.tagsSorter

  • 属性路径:springdoc.swagger-ui.tagsSorter

  • 作用: 定义如何对 Swagger UI 中的标签进行排序。

  • 可选值:

    • alpha: 按照标签名称的字母顺序排列。

  • 示例:

    springdoc:swagger-ui:tagsSorter: alpha

    配置后，标签会按照字母顺序显示。

（5）springdoc.title

  • 属性路径:springdoc.title

  • 作用: 设置整个 API 文档的标题。

  • 示例:

    springdoc:title: 用户管理

    配置后，生成的 API 文档的标题会显示为“用户管理”。

使用
package com.ck.framework.common.springdoc.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** @ClassName SpringDocConfig* @Description* @Author * @Date 2024/8/28 15:55* @Version 1.0*/
@Configuration
public class SpringDocConfig {@Autowiredprivate BaseConfig baseConfig;@Beanpublic OpenAPI createOpenApi() {return new OpenAPI().info(createInfo());}private Info createInfo() {return new Info().contact(createContact()).title(baseConfig.getTitle()).description(baseConfig.getDescription()).version(baseConfig.getVersion());}private Contact createContact() {Contact contact = new Contact();contact.name(baseConfig.getContactName());contact.url(baseConfig.getContactUrl());contact.email(baseConfig.getContactEmail());return contact;}
}
3.控制器处理

需要再Controller里面加上Tag注解

package com.ck.framework.user.controller;import com.ck.framework.common.web.bean.Result;
import com.ck.framework.user.entity.PageResult;
import com.ck.framework.user.entity.dto.UserDto;
import com.ck.framework.user.entity.po.UserPo;
import com.ck.framework.user.entity.req.UserListReq;
import com.ck.framework.user.entity.req.UserReq;
import com.ck.framework.user.service.UserService;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;/*** @ClassName UserController* @Description* @Author * @Date 2024/8/24 0:03* @Version 1.0*/
@RestController
@RequestMapping("/user")
@Tag(name = "用户管理")
public class UserController {@Autowiredprivate UserService userService;@PostMappingpublic Result<Boolean> addUser(@RequestBody UserReq userReq) {UserDto userDto = new UserDto();userDto.setName(userReq.getName());userDto.setAge(userReq.getAge());int num = userService.addUser(userDto);if (num > 0) {return Result.success(true);} else {return Result.fail();}}@DeleteMapping("/{id}")public Result<Boolean> deleteUser(@RequestBody UserReq userReq) {UserDto userDto = new UserDto();userDto.setId(userReq.getId());int num = userService.delUser(userDto);if (num > 0) {return Result.success(true);} else {return Result.fail();}}@GetMappingpublic Result<PageResult<UserPo>> getUserPage(@RequestBody UserListReq userListReq) {UserDto userDto = new UserDto();userDto.setPageIndex(userListReq.getPageIndex());userDto.setPageSize(userListReq.getPageSize());PageResult<UserPo> pageResult = userService.getUserPage(userDto);return Result.success(pageResult);}}
4.访问

5.优点
  1. 无缝集成:
    • 专为 Spring Boot 设计，非常容易集成到 Spring Boot 应用中。
  2. 减少注解:
    • 可以自动解析 Spring MVC 或 Spring WebFlux 控制器，减少了需要添加的注解数量。
  3. 自动化配置:
    • 大量依赖默认配置，无需复杂的手动配置，开箱即用。
  4. 支持最新技术:
    • 支持 Spring Boot 2.x 及更高版本，跟进 Spring 生态系统的最新发展。
  5. 丰富的文档和示例:
    • 提供了良好的文档和示例，帮助开发者快速上手。
6.缺点
  1. 局限性:
    • 专门面向 Spring Boot 项目，不适用于其他框架或原生 Spring 项目。
  2. 功能相对简单:
    • 相对于 Swagger 提供的完整工具链，Springdoc 的功能相对单一，主要聚焦于文档生成。

二、swagger

Swagger是一个用于生成、描述、调用和可视化 RESTful Web 服务的开源框架。它的核心是一个名为 OpenAPI 规范的描述性语言。Swagger 是 Java 应用程序中常用的工具之一，因为它能自动生成 API 文档，并提供一个用户友好的接口来测试 API。

在 Java 项目中使用 Swagger 通常包括以下步骤：

1. 添加依赖项

首先，你需要在你的项目中添加所需的 Swagger 依赖项。以 Maven 项目为例，在pom.xml文件中添加以下依赖：

    <dependencies><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version></dependency></dependencies>
2. 配置 Swagger

添加一个 Swagger 配置类。例如，在 Spring Boot 应用程序中，你可以添加以下内容：

package com.ck.framework.common.swagger.config;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;/*** @ClassName SwaggerConfig* @Description 配置Swagger的类，启用Swagger并定义API文档的相关信息* @Author * @Date 2024/8/28 08:31* @Version 1.0*/
@Configuration  // 表示这是一个配置类
@EnableSwagger2  // 启用Swagger2
public class SwaggerConfig {/*** 创建一个Docket Bean，用于配置Swagger的核心内容，包括哪些包中的API需要生成文档和API的基本信息。** @return Docket对象，用于Swagger的配置*/public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)  // 指定文档类型为Swagger2.apiInfo(apiInfo())  // 配置API信息.select()  // 返回一个ApiSelectorBuilder实例，用于控制哪些接口暴露给swagger.apis(RequestHandlerSelectors.basePackage("com.ck.framework.common.swagger"))  // 选择扫描的包名.paths(PathSelectors.ant("/*"))  // 选择哪些路径的API需要生成文档.build();  // 构建Docket实例}/*** 构建API基本信息，用于页面展示的文档信息。** @return ApiInfo对象，包含相关API的描述信息*/public ApiInfo apiInfo() {return new ApiInfoBuilder().title("")  // 设置文档标题.description(" 测试swagger")  // 设置文档描述信息.contact(new Contact("", "git地址", "zhuchb_0509@163.com"))  // 设置联系人信息.version("1.0")  // 设置文档版本.build();  // 构建ApiInfo实例}
}
3. 将注释添加到控制器中

使用 Swagger 注释描述注册到Controller。例如：

package com.ck.framework.user.controller;import com.ck.framework.common.web.bean.Result;
import com.ck.framework.user.entity.PageResult;
import com.ck.framework.user.entity.dto.UserDto;
import com.ck.framework.user.entity.po.UserPo;
import com.ck.framework.user.entity.req.UserListReq;
import com.ck.framework.user.entity.req.UserReq;
import com.ck.framework.user.service.UserService;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;/*** @ClassName UserController* @Description* @Author * @Date 2024/8/24 0:03* @Version 1.0*/
@RestController
@RequestMapping("/user")
@Api(value = "用户管理")
public class UserController {@Autowiredprivate UserService userService;@PostMappingpublic Result<Boolean> addUser(@RequestBody UserReq userReq) {UserDto userDto = new UserDto();userDto.setName(userReq.getName());userDto.setAge(userReq.getAge());int num = userService.addUser(userDto);if (num > 0) {return Result.success(true);} else {return Result.fail();}}@DeleteMapping("/{id}")public Result<Boolean> deleteUser(@RequestBody UserReq userReq) {UserDto userDto = new UserDto();userDto.setId(userReq.getId());int num = userService.delUser(userDto);if (num > 0) {return Result.success(true);} else {return Result.fail();}}@GetMappingpublic Result<PageResult<UserPo>> getUserPage(@RequestBody UserListReq userListReq) {UserDto userDto = new UserDto();userDto.setPageIndex(userListReq.getPageIndex());userDto.setPageSize(userListReq.getPageSize());PageResult<UserPo> pageResult = userService.getUserPage(userDto);return Result.success(pageResult);}}
4. 访问 Swagger UI

启动你的 Spring Boot 应用程序后，打开浏览器访问http://localhost:8080/swagger-ui.html，你会看到自动生成的 API 文档及其用户界面。

5.优点
  1. 工具链完备:
    • Swagger 提供了全面的工具，包括 Swagger Editor、Swagger Codegen 和 Swagger UI，这些工具可以涵盖从开发到文档化的各个环节。
  2. 广泛支持:
    • 被多个语言和框架广泛支持，几乎成为业界标准。
  3. 丰富的插件和社区支持:
    • 有大量的插件和扩展，可以满足各种自定义需求。
  4. 可视化交互:
    • Swagger UI 提供了极为友好的界面，允许开发者甚至非技术人员进行直接的API测试与调用。
6.缺点
  1. 集成复杂:
    • 对于部分框架或语言，需要较多的配置和集成工作。
  2. 注解依赖:
    • 在某些实现中，需要开发者在代码中添加大量的注解，增加了代码复杂性。

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

相关文章

⭐算法OJ⭐连接所有点的最小费用【最小生成树】（C++实现）Min Cost to Connect All Points

⭐算法OJ⭐连接所有点的最小费用【最小生成树】（C++实现）Min Cost to Connect All Points

文章目录 问题描述解题思路方法1&#xff1a;Kruskal算法&#xff08;推荐&#xff09;代码实现&#xff08;Kruskal Union-Find&#xff09;复杂度分析 方法2&#xff1a;Prim算法代码实现&#xff08;Prim算法&#xff09;复杂度分析 1584. Min Cost to Connect All Points …
阅读更多...
【STM32】知识点介绍一：硬件知识

【STM32】知识点介绍一：硬件知识

文章目录 一、电源引脚简介二、电平信号三、电路分析 一、电源引脚简介 VCC、GND、VDD和VSS是电子电路中常见的术语&#xff0c;代表着不同的电源引脚或电压。 VCC&#xff08;Voltage at the Common Collector&#xff09;&#xff1a;VCC是指集电极&#xff08;Collector&am…
阅读更多...
142. 环形链表 II——考察数学，难！

142. 环形链表 II——考察数学，难！

142. 环形链表 IIhttps://leetcode.cn/problems/linked-list-cycle-ii/ 给定一个链表的头节点 head ，返回链表开始入环的第一个节点。 如果链表无环，则返回 null。 如果链表中有某个节点，可以通过连续跟踪 next 指针再次到达，则链表中存在环。 为了表示给定链表中的环，…
阅读更多...
C# WinForms 中的回调：从性能到技术层面的全面解析

C# WinForms 中的回调：从性能到技术层面的全面解析

回调&#xff08;Callback&#xff09;是现代编程中一种广泛应用的技术&#xff0c;在 C# WinForms 中也有着重要的地位。它允许你将方法作为参数传递给其他方法&#xff0c;等待特定事件或条件触发后执行。回调在事件处理、异步编程、委托等场景中都有着非常重要的应用。本文将…
阅读更多...
FreGS: 3D Gaussian Splatting with Progressive Frequency Regularization论文学习记录

FreGS: 3D Gaussian Splatting with Progressive Frequency Regularization论文学习记录

3. 提出的方法 我们提出了FreGS&#xff0c;一种具有渐进频率正则化的新型3D高斯溅射方法&#xff0c;它是首个从频率角度缓解3D高斯溅射过度重建问题的方法。图2展示了FreGS的概览。第3.1节简要介绍了原始的3D高斯溅射方法&#xff08;3D-GS&#xff09;&#xff0c;包括高斯…
阅读更多...
docker-镜像制作

docker-镜像制作

前言 镜像制作及原因 镜像制作是因为某种需求&#xff0c;官方的镜像无法满足需求&#xff0c;需要我们通过一定手段来自定 义镜像来满足要求。 制作镜像往往因为以下原因 编写的代码如何打包到镜像中直接跟随镜像发布 第三方制作的内容安全性未知&#xff0c;如含有安全漏洞…
阅读更多...
WPF 样式（Style）和模板（Template）

WPF 样式（Style）和模板（Template）

在WPF中&#xff0c;样式&#xff08;Style&#xff09;和模板&#xff08;Template&#xff09;虽然有不同的用途&#xff0c;但它们可以很好地协同工作。样式中可以设置模板的原因是为了提供一种统一的方式来管理和应用控件的外观定义。以下是详细的原因和机制&#xff1a; 1…
阅读更多...
多数据源无缝对接、多维度动态分析和智能化可视化分析

多数据源无缝对接、多维度动态分析和智能化可视化分析

在当今数字化时代&#xff0c;企业数据如同宝藏&#xff0c;而如何有效挖掘并利用这些宝藏&#xff0c;则成为了每个企业都必须面对的挑战。BI&#xff08;商业智能&#xff09;数据可视化分析正是解决这一挑战的关键技术之一。在众多BI数据可视化工具中&#xff0c;奥威BI以其…
阅读更多...
最新文章

Copyright @ 2022~2023