1、概览 设计 REST API 通常使用两种流行的方法：Swagger 和 HATEOAS。这两种方法都旨在使 API 更友好、更易懂，但遵循不同的范式。
本文将带你了解 Swagger 和 HATEOAS 的区别以及一些常见用例。
2、Swagger 是什么？ Swagger 是一套用于构建、记录和使用 REST API 的开源工具。它允许开发人员使用基于 OpenAPI Specification（OAS） 的 JSON 或 YAML 文件来描述其 API 的结构。
来看看 Swagger 的主要功能。
2.1、代码生成 有了 Swagger，我们可以自动生成交互式 API 文档、代码和客户端库。Swagger 还可以用各种编程语言创建服务器存根（Stub）和客户端 SDK，从而加快开发速度。
这是一种 API 优先的方法，它定义了需求与应用程序维护人员之间的契约。
开发人员可以使用 SwaggerHub 等工具，通过提供 Swagger 规范文件为不同的编程语言创建模板代码。
例如，来看看一个简单的 User 端点的 YAML 模板：
openapi: 3.0.1 info: title: User API version: "1.0.0" description: API for managing users. paths: /users: get: summary: Get all users security: - bearerAuth: [] # 端点的安全设置 responses: '200': description: A list of users.
1、概览 在开发环境下使用 Swagger UI 可以很方便地查看、测试 REST 服务。但是出于安全考虑，在生产环境中往往需要禁用 Swagger UI。
2、Swagger 配置 要 使用 SpringDoc 设置 Swagger，需要在配置 Bean 中对其进行定义。
创建 SwaggerConfig 类：
@Configuration public class SwaggerConfig { @Bean public OpenAPI openAPI() { return new OpenAPI().info(new Info().title("SpringDoc Disable SwaggerUI example") .description("SpringDoc Disable SwaggerUI application") .version("v0.0.1")); } } 默认情况下，该配置 Bean 会添加到 Spring Context 中。这样，Swagger 可以在所有环境中使用。
3、使用 Spring Profile 在 Spring 中，可以使用 @Profile 注解来启用或禁用 Bean。
使用 SpEL 表达式来指定在哪些环境中激活 Swagger。
@Profile({"!prod && swagger"}) 如上，在 swagger Profile，且不是 prod Profile 的情况下才会启注解的 Bean。
1、概览 在 Spring Boot 中使用 Swagger 文档时，有时候需要隐藏端点。最常见的情况就是，该端点还在开发中。或者是有一些内部端点，不想暴露给用户。
本文将带你了解如何在 Swagger API 文档中隐藏端点。
2、使用 @ApiIgnore 隐藏端点 可以在 Handler 方法上添加 @ApiIgnore 注解来隐藏端点：
@ApiIgnore @ApiOperation(value = "This method is used to get the author name.") @GetMapping("/getAuthor") public String getAuthor() { return "Umang Budhwar"; } 3、使用 @ApiOperation 隐藏端点 也可以使用 @ApiOperation 来隐藏端点：
@ApiOperation(value = "This method is used to get the current date.", hidden = true) @GetMapping("/getDate") public LocalDate getDate() { return LocalDate.now(); } 将 @ApiOperation 注解的 hidden 属性设置为 true，即可使 Swagger 忽略该端点。
1、简介 本文将带你了解如何在 Spring Boot 中配置 Swagger UI，使其在调用 API 时包含 JWT（JSON Web Token）。
2、Maven 依赖 本例使用 springdoc-openapi-ui 库，它包含了使用 Swagger 和 Swagger UI 所需的所有依赖。
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.7.0</version> </dependency> 3、Swagger 配置 首先，需要配置 JWT SecurityScheme：
private SecurityScheme createAPIKeyScheme() { return new SecurityScheme().type(SecurityScheme.Type.HTTP) .bearerFormat("JWT") .scheme("bearer"); } 然后，配置 OpenAPI Bean，包含 API Info 和 Security Scheme：
@Bean public OpenAPI openAPI() { return new OpenAPI().addSecurityItem(new SecurityRequirement(). addList("Bearer Authentication")) .components(new Components().addSecuritySchemes ("Bearer Authentication", createAPIKeyScheme())) .
1、概览 本文将带你了解如何 Swagger 文档界面中隐藏 BasicErrorController。
3、问题 如果应用中包含了一个 BasicErrorController，Swagger 默认会将其所有端点也包含在生成的文档中。
我们需要提供自定义配置来移除不需要的 Controller。
例如，项目中的 Rest Controller 如下：
@RestController @RequestMapping("good-path") public class RegularRestController { @ApiOperation(value = "This method is used to get the author name.") @GetMapping("/getAuthor") public String getAuthor() { return "Name Surname"; } } 另外，还包含一个继承 BasicErrorController 的 Error Controller：
@Component @RequestMapping("my-error-controller") public class MyErrorController extends BasicErrorController { // basic constructor } 启动应用，访问文档！你可以看到，my-error-controller 包含在生成的文档中：
4、解决办法 有四种方式可以从 Swagger 文档中排除资源。
4.1、通过 basePackage() 方法排除 通过指定 Controller 所在的包，可以排除其他不需要的资源。
1、概览 本文将带你了解如何使用 swagger-maven-plugin 来在 Swagger 中记录枚举，并在 Swagger 编辑器中验证生成的 JSON 文档。
2、Swagger 是啥？ Swagger 是一种开源工具，用于定义基于 REST 的 API。在当今世界，大多数组织都在向微服务和 API 优先的方向发展。Swagger 在设计和记录 API 方面非常方便。它还提供了 Swagger 编辑器、Swagger UI 和 Swagger CodeGen 等各种工具来协助 API 开发。
此外，Swagger 是 OpenAPI 规范或 OAS 的一种实现，OAS 定义了一套用于开发 REST API 的标准，有助于全球各地的组织将编写 API 的过程标准化。
我们应用生成的 JSON 文件也将遵循 OpenAPI 规范。
在 Swagger 中使用 Enum 是个有必要的，有些 API 需要用户只能使用一组特定的预定义值。这些预定义的常量值被称为枚举（Enum）。同样，当 Swagger 公开 API 时，需要要确保用户从这组预定义值中选择一个值，而不是任意的值。
换句话说，需要在 swagger.json 文件中记录枚举，让用户知道可选的选项。
3、实现 实现一个 POST API，用于为组织招聘特定角色的员工（Employee）。角色只能是以下角色之一：Engineer、Clerk、Driver 或 Janitor。
创建 Role 枚举，其中包含 Employee 角色的所有可能值，然后创建一个 Employee 类，将角色作为其属性之一。
1、概览 本文将带你了解 Swagger 中 @Operation 和 @ApiResponse 注解的主要区别和应用场景。
2、用 Swagger 生成文档 Swagger 是一套围绕 OpenAPI 规范构建的开源工具，用于描述整个 API，如暴露的端点、操作、参数、验证方法等。
Swagger 提供了 @Operation 和 @ApiResponse 注解，用于描述 REST API，以及 REST API 的响应。
定义一个示例 Controller：
@RestController @RequestMapping("/customers") class CustomerController { private final CustomerService customerService; public CustomerController(CustomerService customerService) { this.customerService = customerService; } @GetMapping("/{id}") public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) { return ResponseEntity.ok(customerService.getById(id)); } } 3、@Operation @Operation 注解用于描述单个操作。
@Operation(summary = "Gets customer by ID", description= "Customer must exist") @GetMapping("/{id}") public ResponseEntity<CustomerResponse> getCustomer(@PathVariable("id") Long id) { return ResponseEntity.
1、概览 本文介绍了如何在 API 规范中，为同一个响应定义多个不同的对象，以及如何使用该规范生成 Java 代码和 Swagger 文档。
2、问题陈述 定义两个对象（object）。
Car 对象的属性是 owner 和 plate，两者都是 String。 Bike 对象的属性是 owner 和 speed，speed 是一个 Integer。 它们在 OpenAPI 中的描述如下：
Car: type: object properties: owner: type: string plate: type: string Bike: type: object properties: owner: type: string speed: type: integer 我们想描述一个 /vehicle 端点，它将接受 GET 请求，并能返回一个 Car 或一个 Bike。
类似于如下描述：
paths: /vehicle: get: responses: '200': # 返回 Car 或 Bike 接下来介绍在 OpenAPI 2 和 3 规范中的不同实现方式。
1、概览 Springfox 和 SpringDoc 这两个工具简化了 Swagger API 文档的生成和维护。
在本教程中，我们将了解如何在 Spring Boot 应用中更改 Swagger-UI URL 前缀。
2、使用 Springdoc 时更改 Swagger UI URL 前缀 首先，我们可以看看 如何使用 OpenAPI 3.0 生成 REST API 文档。
根据上述教程，我们需要添加如下 SpringDoc 的依赖：
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.0.2</version> </dependency> swagger-ui 的默认 URL 是 http://localhost:8080/swagger-ui.html。
比方说，我们要增加 /myproject 前缀，接下来让我们看看自定义 swagger-UI URL 的两种方法。
2.1、application.properties 我们可以在 application.properties 文件中添加以下属性来修改 swagger-UI URL：
springdoc.swagger-ui.disable-swagger-default-url=true springdoc.swagger-ui.path=/myproject 2.2、配置类 我们也可以通过配置类来实现：
@Component public class SwaggerConfiguration implements ApplicationListener<ApplicationPreparedEvent> { @Override public void onApplicationEvent(final ApplicationPreparedEvent event) { ConfigurableEnvironment environment = event.
1、概览 在本教程中，我们将演示如何使用 Swagger 注解使我们的文档更具描述性。我们会学习如何为 API 的不同部分（如方法、参数、响应等）添加描述，以及如何添加请求/响应示例。
2、项目设置 我们将创建一个简单的 Product API，提供创建和获取 product 的方法。
要从头开始创建 REST API，我们可以按照 Spring 文档中的教程 使用 Spring Boot 创建 RESTful Web 服务。
下一步是为项目设置依赖和配置。我们可以按照 本文 中的步骤使用 Spring REST API 设置 Swagger 2
3、创建 API 创建 Product API 并检查生成的文档。
3.1、Model 定义 Product 类：
public class Product implements Serializable { private long id; private String name; private String price; // 省略 get/set 构造函数 } 3.2、Controller 定义两个 API 方法：
@RestController @Tag(name = "Products API") public class ProductController { @PostMapping("/products") public ResponseEntity<Void> createProduct(@RequestBody Product product) { //creation logic return new ResponseEntity<>(HttpStatus.
