swagger

在生产环境中关闭 Swagger-UI

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。

隐藏 Swagger API 文档中的端点

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 忽略该端点。

Swagger UI 设置 JWT

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())) .

在 Swagger 文档中移除 BasicErrorController

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 所在的包,可以排除其他不需要的资源。

Swagger 记录包含枚举(Enum)参数的文档

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 类,将角色作为其属性之一。

Swagger 中的 @Operation 和 @ApiResponse 注解

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.

Swagger:同一状态码返回不同的 Response 对象

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 规范中的不同实现方式。

在 Spring Boot 中自定义 Swagger URL

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.

设置 Swagger 文档中的示例和描述

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.