springdoc

springdoc-openapi 定义全局的默认 SecurityScheme

1、概览 本文将带你了解如何在 Spring MVC Web 应用中使用 springdoc-openapi 配置默认的全局 Security Scheme,并将其应用为 API 的默认安全配置,以及如何覆盖这些默认的安全配置。 OpenAPI 规范 允许为 API 定义一套 Security Scheme。可以配置 API 全局的安全配置,也可以按端点应用/删除安全配置。 2、设置 构建一个 Spring Boot Web 项目,使用 Maven。 2.1、依赖 该示例有两个依赖。第一个是 spring-boot-starter-web,用于构建 Web 应用。 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>2.7.1</version> </dependency> 另一个依赖是 springdoc-openapi-ui,它用于输出 HTML、JSON 或 YAML 格式的 API 文档: <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.9</version> </dependency> 2.2、启动类 使用 @SpringBootApplication 注解来定义启动类,通过 SpringApplication 类来启动应用: @SpringBootApplication public class DefaultGlobalSecuritySchemeApplication { public static void main(String[] args) { SpringApplication.run(DefaultGlobalSecuritySchemeApplication.class, args); } } 3、springdoc-openapi 基础配置 配置好 Spring MVC 后,来看看 API 语义信息。

在 Springdoc 文档中配置身份认证,以访问需要认证的的端点

1、概览 Springdoc-OpenAPI 是一个为 Spring Boot 应用程序自动生成 API 文档的框架。它实现了 OpenAPI 3 规范,使用它,通过 UI 界面就可以与 API 进行交互,非常方便。 在本教程中,我们将学习如何使用 Spring Security 通过表单登录和 Basic Authentication 来认证 springdoc 中的端点访问。 2、项目设置 创建一个 Spring Boot Web 应用程序,该应用程序将通过 Spring Security 保护 API,并使用 Springdoc 生成文档。 2.1、依赖 首先添加 springdoc-openapi-ui,它整合了 Swagger-UI,用于提供 UI 界面: http://localhost:8080/swagger-ui.html 其次,添加 springdoc-openapi-security,用于为 Spring Security 提供支持: <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.13</version> </dependency> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-security</artifactId> <version>1.6.13</version> </dependency> 2.2、示例 API 创建一个示例 REST Controller,Springdoc 会为其生成文档。 此外,我们将通过 Swagger-UI 来演示与 FooController 中受保护(需要认证)的端点进行交互。 @RestController @RequestMapping(value = "foos", produces = MediaType.

在 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.

使用 Spring Doc 为 Spring REST API 生成 OpenAPI 3.0 文档

1、概览 文档是构建 REST API 的重要组成部分。在本教程中,我们将介绍 Spring Doc,它可简化 API 文档的生成和维护,这些文档基于 OpenAPI 3 规范,适用于 Spring Boot 3.x 应用程序。 2、设置 springdoc-openapi Spring Boot 3.x 要求使用 springdoc-openapi version 2: <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.1.0</version> </dependency> 2.1、 OpenAPI 描述的路径 正确设置依赖后,我们就可以运行应用程序,并在 /v3/api-docs 路径访问 OpenAPI 描述,这是默认路径: http://localhost:8080/v3/api-docs 此外,我们还可以使用 springdoc.api-docs 属性在 application.properties 中自定义描述的路径。例如,我们可以将路径设置为 /api-docs: springdoc.api-docs.path=/api-docs 然后,我们就可以通过以下网址访问文档描述: http://localhost:8080/api-docs OpenAPI 描述定义默认为 JSON 格式。对于 yaml 格式,我们可以从以下网址获取定义: http://localhost:8080/api-docs.yaml 3、整合 Swagger UI 除了生成 OpenAPI 3 规范之外,我们还可以将 springdoc-openapi 与 Swagger UI 集成,以与我们的 API 规范进行交互并测试端点。 Springdoc-openapi 依赖项中已经包含了 Swagger UI,因此我们可以通过如下路径访问 API 文档: