当前位置：首页 > news >正文

在Spring Cloud项目中集成Springdoc OpenAPI生成OpenAPI 3文档的详细解析

news 2026/1/20 22:05:17

在Spring Cloud项目中集成Springdoc OpenAPI生成OpenAPI 3文档的详细解析

在Spring Cloud项目中生成OpenAPI 3文档，可以使用Springdoc OpenAPI。Springdoc OpenAPI提供了一种简单的方法来生成符合OpenAPI 3规范的API文档。以下是详细的步骤和解析，展示如何在Spring Cloud项目中配置Springdoc OpenAPI来生成和展示API文档。

1. 添加依赖

在你的Spring Boot项目的pom.xml文件中添加Springdoc OpenAPI的依赖：

<dependencies><!-- Springdoc OpenAPI dependencies --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.7.0</version></dependency>
</dependencies>

2. 配置OpenAPI

创建一个配置类来设置OpenAPI的信息和分组：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class OpenAPIConfig {@Beanpublic GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public-api").pathsToMatch("/api/**").build();}@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Your API Title").version("1.0").description("API documentation for your service").contact(new Contact().name("Your Name").email("your-email@example.com").url("https://www.example.com")));}
}

3. 配置应用属性

在application.yml或application.properties中配置Springdoc OpenAPI的相关设置：

# application.yml
springdoc:api-docs:path: /v3/api-docsswagger-ui:path: /swagger-ui.html

或在application.properties中：

# application.properties
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

4. 创建示例控制器

确保你有一些控制器来展示API文档。以下是一个示例控制器：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
public class HelloController {@GetMapping("/api/hello")public String sayHello() {return "Hello, World!";}
}

5. 运行应用程序

启动你的Spring Boot应用程序，然后在浏览器中访问http://localhost:8080/swagger-ui.html（根据你的配置调整端口号），你应该能够看到生成的Swagger API文档界面。

6. 解析Springdoc OpenAPI配置

GroupedOpenApi

@Bean
public GroupedOpenApi publicApi() {return GroupedOpenApi.builder().group("public-api").pathsToMatch("/api/**").build();
}

GroupedOpenApi用于创建不同的API组，可以为不同的路径或包配置不同的API组。在上面的例子中，我们创建了一个名为public-api的组，它匹配所有/api/**路径。

OpenAPI

@Bean
public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Your API Title").version("1.0").description("API documentation for your service").contact(new Contact().name("Your Name").email("your-email@example.com").url("https://www.example.com")));
}

OpenAPI对象包含了API的元信息，例如标题、版本、描述和联系信息。这些信息将显示在生成的API文档中。

7. 处理安全性

如果你的API需要安全性配置，例如使用JWT或OAuth2，你需要在OpenAPI配置中添加安全方案：

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;@Bean
public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Your API Title").version("1.0").description("API documentation for your service").contact(new Contact().name("Your Name").email("your-email@example.com").url("https://www.example.com"))).addSecurityItem(new SecurityRequirement().addList("bearerAuth")).components(new Components().addSecuritySchemes("bearerAuth",new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
}

在上述配置中，我们添加了一个名为bearerAuth的安全方案，这个方案是HTTP类型的，使用Bearer格式的JWT。

总结

通过以上步骤和配置，你可以在Spring Cloud项目中生成和展示符合OpenAPI 3规范的API文档。Springdoc OpenAPI提供了简洁且强大的功能来处理API文档的生成，适用于现代微服务架构。