SpringDoc和Swagger使用

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.优点

无缝集成: - 专为 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

文件中添加以下依赖：

    <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地址", "[email protected]"))  // 设置联系人信息
                .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.优点

工具链完备: - Swagger 提供了全面的工具，包括 Swagger Editor、Swagger Codegen 和 Swagger UI，这些工具可以涵盖从开发到文档化的各个环节。
广泛支持: - 被多个语言和框架广泛支持，几乎成为业界标准。
丰富的插件和社区支持: - 有大量的插件和扩展，可以满足各种自定义需求。
可视化交互: - Swagger UI 提供了极为友好的界面，允许开发者甚至非技术人员进行直接的API测试与调用。

6.缺点

集成复杂: - 对于部分框架或语言，需要较多的配置和集成工作。
注解依赖: - 在某些实现中，需要开发者在代码中添加大量的注解，增加了代码复杂性。

标签： java maven spring boot

本文转载自: https://blog.csdn.net/weixin_40116478/article/details/141622491
版权归原作者 蛋白质先生 所有，如有侵权，请联系我们删除。

SpringDoc和Swagger使用

一、SpringDoc

1.添加依赖

2.配置代码

配置解释

使用

3.控制器处理

4.访问

5.优点

6.缺点

二、swagger

1. 添加依赖项

2. 配置 Swagger

3. 将注释添加到控制器中

4. 访问 Swagger UI

5.优点

6.缺点

发表评论

“SpringDoc和Swagger使用”的评论:

关于作者

overfit同步小助手

相关阅读

文章导航