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地址", "[e-mail]"))  // 设置联系人信息.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. 注解依赖:
   • 在某些实现中，需要开发者在代码中添加大量的注解，增加了代码复杂性。