qidao123.com ToB IT社区-企服评测·应用市场»论坛 › 大数据 › 数据仓库与分析 › SpringDoc和Swagger利用

SpringDoc和Swagger利用

[复制链接]
发表于 2025-10-24 05:55:51 | 显示全部楼层 |阅读模式

马上注册，结交更多好友，享用更多功能，让你轻松玩转社区。

您需要 登录 才可以下载或查看，没有账号？立即注册

×
目次
一、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.添加依靠

  1.     <dependencies>
  2.         <dependency>
  3.             <groupId>org.springdoc</groupId>
  4.             <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  5.             <version>2.6.0</version>
  6.         </dependency>
  7.     </dependencies>
复制代码
2.设置代码

添加一个设置类，并添加xml设置
设置表明

  1. springdoc:
  2.   api-docs:
  3.     path: /v3/api-docs
  4.   swagger-ui:
  5.     path: /swagger-ui.html
  6.     operationsSorter: method
  7.     tagsSorter: alpha
复制代码
（1）springdoc.api-docs.path



  • 属性路径:springdoc.api-docs.path
  • 作用: 界说 OpenAPI 文档的访问路径。
  • 默认值:/v3/api-docs
  • 示例:
    1. springdoc:
    2.   api-docs:
    3.     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
  • 示例:
    1. springdoc:
    2.   swagger-ui:
    3.     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）。

  • 示例:
    1. springdoc:
    2.   swagger-ui:
    3.     operationsSorter: method
    复制代码
    设置后，操纵会按照 HTTP 方法的次序体现。
（4）springdoc.swagger-ui.tagsSorter



  • 属性路径:springdoc.swagger-ui.tagsSorter
  • 作用: 界说怎样对 Swagger UI 中的标签举行排序。
  • 可选值:

    • alpha: 按照标署名称的字母次序分列。

  • 示例:
    1. springdoc:
    2.   swagger-ui:
    3.     tagsSorter: alpha
    复制代码
    设置后，标签会按照字母次序体现。
（5）springdoc.title



  • 属性路径:springdoc.title
  • 作用: 设置整个 API 文档的标题。
  • 示例:
    1. springdoc:
    2.   title: 用户管理
    复制代码
    设置后，天生的 API 文档的标题会体现为“用户管理”。
利用

  1. package com.ck.framework.common.springdoc.config;
  3. import io.swagger.v3.oas.models.OpenAPI;
  4. import io.swagger.v3.oas.models.info.Contact;
  5. import io.swagger.v3.oas.models.info.Info;
  6. import org.springframework.beans.factory.annotation.Autowired;
  7. import org.springframework.context.annotation.Bean;
  8. import org.springframework.context.annotation.Configuration;
  10. /**
  11. * @ClassName SpringDocConfig
  12. * @Description
  13. * @Author
  14. * @Date 2024/8/28 15:55
  15. * @Version 1.0
  16. */
  17. @Configuration
  18. public class SpringDocConfig {
  20.     @Autowired
  21.     private BaseConfig baseConfig;
  23.     @Bean
  24.     public OpenAPI createOpenApi() {
  25.         return new OpenAPI()
  26.                 .info(createInfo());
  27.     }
  29.     private Info createInfo() {
  30.         return new Info()
  31.                 .contact(createContact())
  32.                 .title(baseConfig.getTitle())
  33.                 .description(baseConfig.getDescription())
  34.                 .version(baseConfig.getVersion());
  35.     }
  37.     private Contact createContact() {
  38.         Contact contact = new Contact();
  39.         contact.name(baseConfig.getContactName());
  40.         contact.url(baseConfig.getContactUrl());
  41.         contact.email(baseConfig.getContactEmail());
  42.         return contact;
  43.     }
  44. }
复制代码
3.控制器处置惩罚

须要再Controller内里加上Tag注解
  1. package com.ck.framework.user.controller;
  3. import com.ck.framework.common.web.bean.Result;
  4. import com.ck.framework.user.entity.PageResult;
  5. import com.ck.framework.user.entity.dto.UserDto;
  6. import com.ck.framework.user.entity.po.UserPo;
  7. import com.ck.framework.user.entity.req.UserListReq;
  8. import com.ck.framework.user.entity.req.UserReq;
  9. import com.ck.framework.user.service.UserService;
  10. import io.swagger.v3.oas.annotations.tags.Tag;
  11. import org.springframework.beans.factory.annotation.Autowired;
  12. import org.springframework.web.bind.annotation.*;
  14. /**
  15. * @ClassName UserController
  16. * @Description
  17. * @Author
  18. * @Date 2024/8/24 0:03
  19. * @Version 1.0
  20. */
  21. @RestController
  22. @RequestMapping("/user")
  23. @Tag(name = "用户管理")
  24. public class UserController {
  26.     @Autowired
  27.     private UserService userService;
  29.     @PostMapping
  30.     public Result<Boolean> addUser(@RequestBody UserReq userReq) {
  31.         UserDto userDto = new UserDto();
  32.         userDto.setName(userReq.getName());
  33.         userDto.setAge(userReq.getAge());
  34.         int num = userService.addUser(userDto);
  35.         if (num > 0) {
  36.             return Result.success(true);
  37.         } else {
  38.             return Result.fail();
  39.         }
  40.     }
  42.     @DeleteMapping("/{id}")
  43.     public Result<Boolean> deleteUser(@RequestBody UserReq userReq) {
  44.         UserDto userDto = new UserDto();
  45.         userDto.setId(userReq.getId());
  46.         int num = userService.delUser(userDto);
  47.         if (num > 0) {
  48.             return Result.success(true);
  49.         } else {
  50.             return Result.fail();
  51.         }
  52.     }
  54.     @GetMapping
  55.     public Result<PageResult<UserPo>> getUserPage(@RequestBody UserListReq userListReq) {
  56.         UserDto userDto = new UserDto();
  57.         userDto.setPageIndex(userListReq.getPageIndex());
  58.         userDto.setPageSize(userListReq.getPageSize());
  59.         PageResult<UserPo> pageResult = userService.getUserPage(userDto);
  60.         return Result.success(pageResult);
  61.     }
  63. }
复制代码
4.访问


5.长处


  • 无缝集成:

    • 专为 Spring Boot 筹划，非常容易集成到 Spring Boot 应用中。

  • 镌汰注解:

    • 可以主动剖析 Spring MVC 或 Spring WebFlux 控制器，镌汰了须要添加的注解数目。

  • 主动化设置:

    • 大量依靠默认设置，无需复杂的手动设置，开箱即用。

  • 支持最新技能:

    • 支持 Spring Boot 2.x 及更高版本，跟进 Spring 生态体系的最新发展。

  • 丰富的文档和示例:

    • 提供了良好的文档和示例，资助开发者快速上手。

6.缺点


  • 范围性:

    • 专门面向 Spring Boot 项目，不实用于其他框架或原生 Spring 项目。

  • 功能相对简朴:

    • 相对于 Swagger 提供的完备工具链，Springdoc 的功能相对单一，紧张聚焦于文档天生。

二、swagger

Swagger是一个用于天生、形貌、调用和可视化 RESTful Web 服务的开源框架。它的核心是一个名为 OpenAPI 规范的形貌性语言。Swagger 是 Java 应用步调中常用的工具之一，由于它能主动天生 API 文档，并提供一个用户友爱的接口来测试 API。
在 Java 项目中利用 Swagger 通常包罗以下步调：
1. 添加依靠项

起首，你须要在你的项目中添加所需的 Swagger 依靠项。以 Maven 项目为例，在pom.xml文件中添加以下依靠：
  1.     <dependencies>
  2.         <dependency>
  3.             <groupId>io.springfox</groupId>
  4.             <artifactId>springfox-swagger-ui</artifactId>
  5.             <version>3.0.0</version>
  6.         </dependency>
  7.         <dependency>
  8.             <groupId>io.springfox</groupId>
  9.             <artifactId>springfox-swagger2</artifactId>
  10.             <version>3.0.0</version>
  11.         </dependency>
  12.     </dependencies>
复制代码
2. 设置 Swagger

添加一个 Swagger 设置类。比方，在 Spring Boot 应用步调中，你可以添加以下内容：
  1. package com.ck.framework.common.swagger.config;
  3. import org.springframework.context.annotation.Configuration;
  4. import springfox.documentation.builders.ApiInfoBuilder;
  5. import springfox.documentation.builders.PathSelectors;
  6. import springfox.documentation.builders.RequestHandlerSelectors;
  7. import springfox.documentation.service.ApiInfo;
  8. import springfox.documentation.service.Contact;
  9. import springfox.documentation.spi.DocumentationType;
  10. import springfox.documentation.spring.web.plugins.Docket;
  11. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  13. /**
  14. * @ClassName SwaggerConfig
  15. * @Description 配置Swagger的类，启用Swagger并定义API文档的相关信息
  16. * @Author
  17. * @Date 2024/8/28 08:31
  18. * @Version 1.0
  19. */
  20. @Configuration  // 表示这是一个配置类
  21. @EnableSwagger2  // 启用Swagger2
  22. public class SwaggerConfig {
  23.     /**
  24.      * 创建一个Docket Bean，用于配置Swagger的核心内容，包括哪些包中的API需要生成文档和API的基本信息。
  25.      *
  26.      * @return Docket对象，用于Swagger的配置
  27.      */
  28.     public Docket createRestApi() {
  29.         return new Docket(DocumentationType.SWAGGER_2)  // 指定文档类型为Swagger2
  30.                 .apiInfo(apiInfo())  // 配置API信息
  31.                 .select()  // 返回一个ApiSelectorBuilder实例，用于控制哪些接口暴露给swagger
  32.                 .apis(RequestHandlerSelectors.basePackage("com.ck.framework.common.swagger"))  // 选择扫描的包名
  33.                 .paths(PathSelectors.ant("/*"))  // 选择哪些路径的API需要生成文档
  34.                 .build();  // 构建Docket实例
  35.     }
  37.     /**
  38.      * 构建API基本信息，用于页面展示的文档信息。
  39.      *
  40.      * @return ApiInfo对象，包含相关API的描述信息
  41.      */
  42.     public ApiInfo apiInfo() {
  43.         return new ApiInfoBuilder()
  44.                 .title("")  // 设置文档标题
  45.                 .description(" 测试swagger")  // 设置文档描述信息
  46.                 .contact(new Contact("", "git地址", "[email protected]"))  // 设置联系人信息
  47.                 .version("1.0")  // 设置文档版本
  48.                 .build();  // 构建ApiInfo实例
  49.     }
  50. }
复制代码
3. 将解释添加到控制器中

利用 Swagger 解释形貌注册到Controller。比方：
  1. package com.ck.framework.user.controller;
  3. import com.ck.framework.common.web.bean.Result;
  4. import com.ck.framework.user.entity.PageResult;
  5. import com.ck.framework.user.entity.dto.UserDto;
  6. import com.ck.framework.user.entity.po.UserPo;
  7. import com.ck.framework.user.entity.req.UserListReq;
  8. import com.ck.framework.user.entity.req.UserReq;
  9. import com.ck.framework.user.service.UserService;
  10. import io.swagger.annotations.Api;
  11. import org.springframework.beans.factory.annotation.Autowired;
  12. import org.springframework.web.bind.annotation.*;
  14. /**
  15. * @ClassName UserController
  16. * @Description
  17. * @Author
  18. * @Date 2024/8/24 0:03
  19. * @Version 1.0
  20. */
  21. @RestController
  22. @RequestMapping("/user")
  23. @Api(value = "用户管理")
  24. public class UserController {
  26.     @Autowired
  27.     private UserService userService;
  29.     @PostMapping
  30.     public Result<Boolean> addUser(@RequestBody UserReq userReq) {
  31.         UserDto userDto = new UserDto();
  32.         userDto.setName(userReq.getName());
  33.         userDto.setAge(userReq.getAge());
  34.         int num = userService.addUser(userDto);
  35.         if (num > 0) {
  36.             return Result.success(true);
  37.         } else {
  38.             return Result.fail();
  39.         }
  40.     }
  42.     @DeleteMapping("/{id}")
  43.     public Result<Boolean> deleteUser(@RequestBody UserReq userReq) {
  44.         UserDto userDto = new UserDto();
  45.         userDto.setId(userReq.getId());
  46.         int num = userService.delUser(userDto);
  47.         if (num > 0) {
  48.             return Result.success(true);
  49.         } else {
  50.             return Result.fail();
  51.         }
  52.     }
  54.     @GetMapping
  55.     public Result<PageResult<UserPo>> getUserPage(@RequestBody UserListReq userListReq) {
  56.         UserDto userDto = new UserDto();
  57.         userDto.setPageIndex(userListReq.getPageIndex());
  58.         userDto.setPageSize(userListReq.getPageSize());
  59.         PageResult<UserPo> pageResult = userService.getUserPage(userDto);
  60.         return Result.success(pageResult);
  61.     }
  63. }
复制代码
4. 访问 Swagger UI

启动你的 Spring Boot 应用步调后，打开欣赏器访问http://localhost:8080/swagger-ui.html，你会看到主动天生的 API 文档及其用户界面。
5.长处


  • 工具链完备:

    • Swagger 提供了全面的工具，包罗 Swagger Editor、Swagger Codegen 和 Swagger UI，这些工具可以涵盖从开发到文档化的各个环节。

  • 广泛支持:

    • 被多个语言和框架广泛支持，险些成为业界尺度。

  • 丰富的插件和社区支持:

    • 有大量的插件和扩展，可以满意各种自界说需求。

  • 可视化交互:

    • Swagger UI 提供了极为友爱的界面，允许开发者以致非技能职员举行直接的API测试与调用。

6.缺点


  • 集成复杂:

    • 对于部门框架或语言，须要较多的设置和集成工作。

  • 注解依靠:

    • 在某些实现中，须要开发者在代码中添加大量的注解，增长了代码复杂性。
回复

使用道具 举报

返回列表

慢吞云雾缓吐愁
+ 我要发帖

登录后关闭弹窗

登录参与点评抽奖  加入IT实名职场社区
去登录
快速回复 返回顶部 返回列表