欢迎来到尧图网

客户服务 关于我们

您的位置：首页 > 新闻 > 资讯 > SpringDoc和Swagger使用

SpringDoc和Swagger使用

2025/1/27 12:32:09 来源：https://blog.csdn.net/egekm_sefg/article/details/145272914  浏览:  次   关键词：SpringDoc和Swagger使用

目录

一、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. 注解依赖:
    • 在某些实现中，需要开发者在代码中添加大量的注解，增加了代码复杂性。

版权声明:

本网仅为发布的内容提供存储空间，不对发表、转载的内容提供任何形式的保证。凡本网注明“来源：XXX网络”的作品，均转载自其它媒体，著作权归作者所有，商业转载请联系作者获得授权，非商业转载请注明出处。

我们尊重并感谢每一位作者，均已注明文章来源和作者。如因作品内容、版权或其它问题，请及时与我们联系，联系邮箱：809451989@qq.com，投稿邮箱：809451989@qq.com

相关资讯

热文排行

最新新闻

推荐新闻

热搜词

STM32 ST7735 128*160 docker部署的gitlab迁移 MYSQL主从同步----1、基于binlog 2、基于gtid MySQL中大量数据优化方案 openssl s_server源码剥离 Spring MVC流程一张图理解