代码编织梦想

目录

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

版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/weixin_40116478/article/details/141622491

Swagger2 迁移至 SpringDoc openapi-爱代码爱编程

由于springfox swagger在最新的springboot 2.6.x版本中频频报错无法使用,因此计划迁移至springdoc。 这里仅记录个人使用经验,更具体的信息见官方文档。 一、导入依赖 <dependency> <groupId>org.springdoc</groupId>

神器 SpringDoc 横空出世,最适合 SpringBoot 的API文档工具来了-爱代码爱编程

之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库,上了下官网发现已经有接近两年没出新版本了!前几天升级了SpringBoot 2.6.x 版本,发现这个库的兼容性也越来越不好了,有的常用注解属性被废弃了居然都没提供替代!无意中发现了另一款Swagger库SpringDoc,试用了一下非常不错,推荐给大家! S

springboot学习(七十三) springboot中使用springdoc替换swagger(springfox)_码农-文若书生的博客-爱代码爱编程

文章目录 前言一、springdoc介绍二、使用步骤1.引入库2. 创建一个spring配置类,添加springdoc的配置3. 常用的swagger注解和springdoc的对应关系4. 一个接口类的示例5. 配置

springboot集成swagger,前后端接口文档解决方案-爱代码爱编程

一个不断在迭代的项目,Controller层与POJO层肯定会是经常变动的,在目前前后端分离的大环境背景下有一份接口文档可以极大减少项目组成员之间的交流成本,也能支持自动化测试,但靠人工维护该文档总是不够稳妥,因此我们

用spring doc代替swagger-爱代码爱编程

1 OpenApi OpenApi 是一个业界的 API 文档标准,是一个规范,这个规范目前有两大实现,分别是: SpringFoxSpringDoc 其中 SpringFox 其实也就是我们之前所说的 Swagger

springdoc 使用-爱代码爱编程

1、引入依赖 <!-- 文档集成 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-webmvc-core</artifactId> <vers

springdoc使用_ org.springdoc

Java spring restful 1024程序员节

文章目录 1.SpringDoc简介2.SpringDoc基础使用 1.SpringDoc简介 SpringDoc是一款可以结合SpringBoot使用的API文档生成工具 2.Spring

『百日百题 · 基础篇』备战面试,坚持刷题 第十二话——异常处理和集合类!-爱代码爱编程

本专栏『百日百题』长期更新,一起加入本刷题计划,一起成长吧! 文章目录 前言JAVA37 判断学生成绩【异常处理】JAVA38 字符串去重【集合类】JAVA39 集合遍历【集合类】结语

springboot3 集成springdoc/swagger、knife4j_springboot 3.x 集成knife4j-爱代码爱编程

文章目录 前言 使用SpringDoc替代SpringFox 1. SpringDoc简介 2. 切换到SpringDoc的一些注意事项

springdoc api文档工具集成springboot -爱代码爱编程

1、引言 之前在Spring Boot项目中一直使用的是SpringFox提供的Swagger库,发现已经超过3年没出新版本了!SpringDoc是一款可以结合Spring Boot使用的API文档生成工具,基于Op