springdoc和swagger使用-爱代码爱编程
目录
(3)springdoc.swagger-ui.operationsSorter
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
- 示例:
配置后,API 文档可以通过springdoc: api-docs: path: /v3/api-docs
http://<host>:<port>/v3/api-docs
访问。
(2)springdoc.swagger-ui.path
- 属性路径:
springdoc.swagger-ui.path
- 作用: 定义 Swagger UI 的访问路径。
- 默认值:
/swagger-ui.html
- 示例:
配置后,Swagger UI 可以通过springdoc: swagger-ui: path: /swagger-ui.html
http://<host>:<port>/swagger-ui.html
访问。
(3)springdoc.swagger-ui.operationsSorter
- 属性路径:
springdoc.swagger-ui.operationsSorter
- 作用: 定义如何对 Swagger UI 中的操作进行排序。
- 可选值:
alpha
: 按照操作名称的字母顺序排列。method
: 按照 HTTP 方法进行排序(如 GET, POST, PUT, DELETE)。
- 示例:
配置后,操作会按照 HTTP 方法的顺序显示。springdoc: swagger-ui: operationsSorter: method
(4)springdoc.swagger-ui.tagsSorter
- 属性路径:
springdoc.swagger-ui.tagsSorter
- 作用: 定义如何对 Swagger UI 中的标签进行排序。
- 可选值:
alpha
: 按照标签名称的字母顺序排列。
- 示例:
配置后,标签会按照字母顺序显示。springdoc: swagger-ui: tagsSorter: alpha
(5)springdoc.title
- 属性路径:
springdoc.title
- 作用: 设置整个 API 文档的标题。
- 示例:
配置后,生成的 API 文档的标题会显示为“用户管理”。springdoc: title: 用户管理
使用
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地址", "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.优点
- 工具链完备:
- Swagger 提供了全面的工具,包括 Swagger Editor、Swagger Codegen 和 Swagger UI,这些工具可以涵盖从开发到文档化的各个环节。
- 广泛支持:
- 被多个语言和框架广泛支持,几乎成为业界标准。
- 丰富的插件和社区支持:
- 有大量的插件和扩展,可以满足各种自定义需求。
- 可视化交互:
- Swagger UI 提供了极为友好的界面,允许开发者甚至非技术人员进行直接的API测试与调用。
6.缺点
- 集成复杂:
- 对于部分框架或语言,需要较多的配置和集成工作。
- 注解依赖:
- 在某些实现中,需要开发者在代码中添加大量的注解,增加了代码复杂性。