SpringDoc和Swagger使用

已于 2024-08-30 10:36:03 修改
阅读量794 收藏 13
点赞数 15
分类专栏： Java修炼之旅 文章标签： java maven spring boot
于 2024-08-30 10:35:49 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_40116478/article/details/141622491
版权

目录

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

蛋白质先生
关注
专栏目录
SpringBoot3 集成SpringDoc/Swagger、Knife4j
一碗清深的博客
11-17 565
本文将介绍如何使用SpringDoc替代SpringFox，并提供了一些注意事项和示例代码。希望通过本文的介绍，能够帮助大家更好地理解和使用SpringDoc，提升API文档的编写和管理效率。让我们一起开始吧！
神器 SpringDoc 横空出世，最适合 SpringBoot 的API文档工具来了
wdjnb的博客
03-23 7440
之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库，上了下官网发现已经有接近两年没出新版本了！前几天升级了SpringBoot 2.6.x 版本，发现这个库的兼容性也越来越不好了，有的常用注解属性被废弃了居然都没提供替代！无意中发现了另一款Swagger库SpringDoc，试用了一下非常不错，推荐给大家！ SpringDoc简介 SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有1.7K+.
Swagger API 文档 | SpringDoc 入门及功能介绍
甘蓝的专栏
04-12 938
Swagger API 文档，SpringDoc 入门及功能介绍。
SpringDoc --＞ Swagger的完美替代品 使用详解【可完全匹配新版Springboot】可视化RESTful风格 Web 服务接口api文档
杨大仙
03-06 6727
使用了最新 SpringBoot 版本的朋友们在使用 swagger 时一定都碰到了很多烦恼，各种报错。废话不多说，既然你看到这里就说明你已经查阅了很多资料，对swagger有了一定的了解。话不多说，直接上菜。 造成问题的原因 当然咯，上菜之前咱还是得讲解一下，为何频频出错；原因很简单，随着时间的推移，springboot 一直在更新迭代，而 swagger 已经1年多没有再进行升级（当前时间：北京时间3月6日17：38分），因此版本已经不再兼容； 上菜 我当前所...
spring.doc
02-20
复习知识整理文档，其中介绍了spring的知识和注意点，还包含面试中常被提及的知识，帮助你快速回忆和复习知识，温故知新
springdoc 使用
zhanghongcai的专栏
08-23 1035
在application.yml。-- 文档集成 -->
SpringDoc使用
liuy__257
10-17 1982
文章目录1.SpringDoc简介2.SpringDoc基础使用 1.SpringDoc简介 SpringDoc是一款可以结合SpringBoot使用的API文档生成工具 2.SpringDoc基础使用 POM文件 <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version&gt
用Spring Doc代替Swagger
热门推荐
吴名氏的博客
04-12 11万+
用Spring Doc代替Swagger
Swagger2 迁移至 SpringDoc openapi
lhlyzh的博客
12-12 1084
由于`springfox swagger`在最新的`springboot 2.6.x`版本中频频报错无法使用，因此计划迁移至`springdoc`。
springdoc和swagger哪个好用
05-26
Springdoc是一个基于Spring Boot的API文档生成器，它与Spring Boot集成得非常好，支持自动化生成API文档，具有易于使用和可扩展性的特点。 Swagger是一个独立的API文档生成器，它提供了一个交互式的API文档界面，...
Spring doc 文档
07-30
Spring doc 文档
Spring doc
06-21
很全面的Spring的Api 说明和DOC 很全面的Spring的Api 说明和DOC 很全面的Spring的Api 说明和DOC 很全面的Spring的Api 说明和DOC
SpringBoot集成Swagger，前后端接口文档解决方案。集成SpringDoc，支持SpringBoot3.x。
头好重好重的博客
01-21 3482
一个不断在迭代的项目，Controller层与POJO层肯定会是经常变动的，在目前前后端分离的大环境背景下有一份接口文档可以极大减少项目组成员之间的交流成本，也能支持自动化测试，但靠人工维护该文档总是不够稳妥，因此我们可以使用Swagger或SpringDoc，为响应式接口文档提供了一种解决方案。
Swagger API 文档 | SpringCloudGateway 集成 SpringDoc
最新发布
甘蓝的专栏
04-15 1639
Spring Cloud Gateway 集成 SpringDoc，实现 Swagger API 文档管理。
01_学习springdoc的基本使用
ShiJunzhiCome的博客
02-01 1万+
网上冲浪🏄🏻‍♂️时，无意间发现 java web 应用程序的在线接口文档，除了耳熟能详的 swagger 之外，还有个 springdoc。这也许就叫惊喜( ͡• ͜ʖ ͡• )还记得要使用 swagger2 的话，springboot 项目里面需要引入 springfox 的依赖。swagger2 遵循的是 OpenAPI 2 规范。现在已经有了 OpenAPI 3 规范，springdoc 便是 OpenAPI 3 和 springboot 的结合，是 springfox 的完美替代品。
【SpringDoc】项目中使用SpringDoc管理与测试接口
apple_51673523的博客
09-26 718
SpringDoc是一个用于生成和展示API文档的开源库，它基于Spring Boot和OpenAPI规范。它提供了一种简单而强大的方式来自动生成API文档，并且与Spring框架无缝集成。自动生成API文档：SpringDoc可以根据Spring Boot程序中的代码、注解和配置自动生成API文档。它会解析控制器、路径映射、请求和响应对象，并将它们转换为清晰的API文档。我们只需要添加一些注解和配置，SpringDoc就能够自动扫描和解析代码，并生成相应的API文档。支持OpenAPI规范。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值