SpringDoc和Swagger使用

news2025/3/24 9:44:46

目录

一、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-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: 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 {

    @Autowired
    private BaseConfig baseConfig;

    @Bean
    public 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 {

    @Autowired
    private UserService userService;

    @PostMapping
    public 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();
        }
    }

    @GetMapping
    public 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 {

    @Autowired
    private UserService userService;

    @PostMapping
    public 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();
        }
    }

    @GetMapping
    public 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.coloradmin.cn/o/2320053.html

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

相关文章

asp.net core mvc模块化开发

asp.net core mvc模块化开发

razor类库 新建PluginController using Microsoft.AspNetCore.Mvc;namespace RazorClassLibrary1.Controllers {public class PluginController : Controller{public IActionResult Index(){return View();}} }Views下Plugin下新建Index.cshtml {ViewBag.Title "插件页…
阅读更多...
第2.2节 Android Jacoco插件覆盖率采集

第2.2节 Android Jacoco插件覆盖率采集

JaCoCo&#xff08;Java Code Coverage&#xff09;是一款开源的代码覆盖率分析工具&#xff0c;适用于Java和Android项目。它通过插桩技术统计测试过程中代码的执行情况&#xff0c;生成可视化报告&#xff0c;帮助开发者评估测试用例的有效性。在github上开源的项目&#xff…
阅读更多...
Vue3中router最佳封装落地

Vue3中router最佳封装落地

文章目录 前言一、拆分路由文件夹&#xff1f;二、main.ts中注册路由总结 前言 router在使用过程中如果我们直接在一个文件的一个数组中配置&#xff0c;最后路由越来越多会导致不易管理&#xff0c;我们可以将一个页面的路由配置在一个数组中最后统一导入&#xff0c;这样就会…
阅读更多...
网络爬虫【爬虫库request】

网络爬虫【爬虫库request】

我叫不三不四&#xff0c;很高兴见到大家&#xff0c;欢迎一起学习交流和进步 今天来讲一讲爬虫 Requests是Python的一个很实用的HTTP客户端库&#xff0c;完全满足如今网络爬虫的需求。与Urllib对比&#xff0c;Requests不仅具备Urllib的全部功能&#xff1b;在开发使用上&…
阅读更多...
aws(学习笔记第三十四课) dockerized-app with asg-alb

aws(学习笔记第三十四课) dockerized-app with asg-alb

aws(学习笔记第三十四课) dockerized-app with asg-alb 使用cdk生成dockerized-app并使用AutoScalingGroup和ApplicationLoaderBalancer 学习内容&#xff1a; 使用cdk生成dockerized-app并使用AutoScalingGroup和ApplicationLoaderBalancer在AutoScalingGroup中使用efs以及R…
阅读更多...
嵌入式c学习七

嵌入式c学习七

c语言指针&#xff1a;程序需要载入内存中运行&#xff0c;在32bit系统中内存地址的范围是&#xff1a;0x0000 0000-0xFFFF FFFF&#xff0c;内存大小为4GB&#xff0c;内存地址指的是内存单元的编号是固定的&#xff0c;本身就是一个整数&#xff0c;对于32bit系统&#xff0c…
阅读更多...
软考通关利器：中级软件设计师结构化开发核心考点

软考通关利器：中级软件设计师结构化开发核心考点

简介&#xff1a; 作为国家软考中级认证的核心科目&#xff0c;“软件设计师” 结构化开发能力是职业进阶的黄金敲门砖。本模块聚焦考试大纲高频考点&#xff0c;深度解析需求建模、结构化分析方法&#xff08;SA/SD&#xff09;、模块设计原则、数据流图&#xff08;DFD&#…
阅读更多...
【Linux】Hadoop-3.4.1的伪分布式集群的初步配置

【Linux】Hadoop-3.4.1的伪分布式集群的初步配置

配置步骤 一、检查环境 JDK # 目前还是 JDK8 最适合 Hadoop java -version echo $JAVA_HOME Hadoop hadoop version echo $HADOOP_HOME 二、配置SSH免密登录 Hadoop需要通过SSH管理节点&#xff08;即使在伪分布式模式下&#xff09; sudo apt install openssh-server …
阅读更多...
楼宇自控系统的结构密码：总线与分布式结构方式的差异与应用

楼宇自控系统的结构密码：总线与分布式结构方式的差异与应用

在现代建筑中&#xff0c;为了实现高效、智能的管理&#xff0c;楼宇自控系统变得越来越重要。它就像建筑的 智能管家&#xff0c;可自动控制照明、空调、通风等各种机电设备&#xff0c;让建筑运行更顺畅&#xff0c;还能节省能源成本。而在楼宇自控系统里&#xff0c;有两种关…
阅读更多...
Fourier-Lerobot——把斯坦福人形动作策略iDP3封装进了Lerobot(含我司七月人形研发落地实践)

Fourier-Lerobot——把斯坦福人形动作策略iDP3封装进了Lerobot(含我司七月人形研发落地实践)

前言 近期在抠lerobot源码时&#xff0c;看到其封装了ALOHA ACT、diffusion policy、π0时&#xff0c;我就在想&#xff0c;lerobot其实可以再封装下idp3 我甚至考虑是否从我联合带的那十几个具身研究生中选几个同学做下这事&#xff0c;对他们也是很好的历练然当25年3.18日…
阅读更多...
系统架构设计知识体系总结

系统架构设计知识体系总结

1.技术选型 1.什么是技术选型&#xff1f; 技术选型是指评估和选择在项目或系统开发中使用的最合适的技术和工具的过程。这涉及考虑基于其能力、特性、与项目需求的兼容性、可扩展性、性能、维护和其他因素的各种可用选项。技术选型的目标是确定与项目目标相符合、能够有效解…
阅读更多...
计划管理工具应该具备的能（甘特图）

计划管理工具应该具备的能（甘特图）

在当今快节奏的项目管理环境中&#xff0c;高效地规划和跟踪项目进度是至关重要的。甘特图&#xff0c;作为项目管理领域的经典工具&#xff0c;以其直观的时间轴和任务分配方式&#xff0c;深受项目管理者的青睐。 随着数字化时代的到来&#xff0c;甘特图线上编辑器应运而生&…
阅读更多...
简单实用！百度AI + Raphael AI = 免费生图

简单实用！百度AI + Raphael AI = 免费生图

简单实用&#xff01;百度AI Raphael AI 免费生图 -- ![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/b55eda9141d34697b05db0cd60f62b75.png#pic_center) 第一步&#xff1a;下载或截取一些好看的图片当参考图片 第二步&#xff1a;用百度AI描述你想要的图片&…
阅读更多...
2025-03-22 学习记录--C/C++-C 库函数 - getchar()

2025-03-22 学习记录--C/C++-C 库函数 - getchar()

C 库函数 - getchar() ⭐️ C 标准库 - <stdio.h> &#xff08;一&#xff09;、函数声明 &#x1f36d; int getchar(void)从标准输入 stdin 获取一个字符&#xff08;一个无符号字符&#xff09;。 参数&#xff1a;&#x1f380; NA 返回值&#xff1a;&#x1f38…
阅读更多...
APM 仿真遥控指南

APM 仿真遥控指南

地面站开发了一段时间了&#xff0c;由于没有硬件&#xff0c;所以一直在 APM 模拟器中验证。我们已经实现了 MAVLink 消息接收和解析&#xff0c;显示无人机状态&#xff0c;给无人机发送消息&#xff0c;实现一键起飞&#xff0c;飞往指定地点&#xff0c;降落&#xff0c;返…
阅读更多...
BBR 和 CUBIC 对长肥管道的不同反应

BBR 和 CUBIC 对长肥管道的不同反应

有个关于 CUBIC(等一众 AIMD-based cc) 和 BBR 在长肥管道中的行为比较挺有趣&#xff0c;它们的表现竟然截然相反&#xff1a; CUBIC 流共存&#xff0c;RTT 越大&#xff0c;Goodput 越低&#xff1b;BBR 流共存&#xff0c;RTT 越大&#xff0c;Goodput 越高。 前一个被看…
阅读更多...
架构师面试（十九）：IM 架构

架构师面试（十九）：IM 架构

问题 IM 系统从架构模式上包括 【介绍人模式】和 【代理人模式】。介绍人模式也叫直连模式&#xff0c;消息收发不需要服务端的参与&#xff0c;即客户端之间直连的方式&#xff1b;代理人模式也叫中转模式&#xff0c;消息收发需要服务端进行中转。 下面关于这两类模式描述的…
阅读更多...
Spring框架入门指南：从Hello World到IOC容器

Spring框架入门指南：从Hello World到IOC容器

第一章&#xff1a;Spring框架的介绍 1. Spring框架的概述 Spring是一个开放源代码的设计层面框架&#xff0c;它解决的是业务逻辑层和其他各层的松耦合问题&#xff0c;因此它将面向接口的编程思想贯穿整个系统应用。 Spring是于2003 年兴起的一个轻量级的Java开发框架&…
阅读更多...
嵌入式电路设计软件个人安装步骤分享

嵌入式电路设计软件个人安装步骤分享

各位小伙伴大家好，今天给大家分享一个，电路设计软件的安装方法，希望对大家有所帮助。 一、下载【Multisim14.0安装包】： 链接：夸克网盘分享 提取码：kHSP 电脑安装Multisim14.0并且汉化 准备安装包以及汉化包双击“NI_Circuit_Design_Suite_14_0【海量免费资源：kebaiwan…
阅读更多...
git | 回退版本 并保存当前修改到stash，在进行整合。[git checkout | git stash 等方法 ]

git | 回退版本 并保存当前修改到stash，在进行整合。[git checkout | git stash 等方法 ]

目录 一些常见命令&#xff1a; git 回退版本 一、临时回退&#xff08;不会修改历史&#xff0c;可随时回到当前版本&#xff09; 方法1&#xff1a;git checkout HEAD~1 二、永久回退&#xff08;改变分支指向&#xff09; 方法2&#xff1a;git reset 1. 保留修改&am…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023