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

在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的依赖:

xml 复制代码
<dependencies>
    <!-- Springdoc OpenAPI dependencies -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.7.0</version>
    </dependency>
</dependencies>

2. 配置OpenAPI

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

java 复制代码
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 {

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

    @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")));
    }
}

3. 配置应用属性

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

yaml 复制代码
# application.yml
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

或在application.properties中:

bash 复制代码
# application.properties
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

4. 创建示例控制器

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

java 复制代码
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

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

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

OpenAPI

java 复制代码
@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配置中添加安全方案:

java 复制代码
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文档的生成,适用于现代微服务架构。

相关推荐
何中应14 分钟前
Spring Boot中选择性加载Bean的几种方式
java·spring boot·后端
小高不明1 小时前
仿 RabbitMQ 的消息队列3(实战项目)
java·开发语言·spring·rabbitmq·mybatis
web2u1 小时前
MySQL 中如何进行 SQL 调优?
java·数据库·后端·sql·mysql·缓存
michael.csdn1 小时前
Spring Boot & MyBatis Plus 版本兼容问题(记录)
spring boot·后端·mybatis plus
Ciderw2 小时前
Golang并发机制及CSP并发模型
开发语言·c++·后端·面试·golang·并发·共享内存
Мартин.2 小时前
[Meachines] [Easy] Help HelpDeskZ-SQLI+NODE.JS-GraphQL未授权访问+Kernel<4.4.0权限提升
后端·node.js·graphql
程序员牛肉2 小时前
不是哥们?你也没说使用intern方法把字符串对象添加到字符串常量池中还有这么大的坑啊
后端
烛阴2 小时前
Go 语言进阶必学:&^ 操作符,高效清零的秘密武器!
后端·go
Yeats_Liao2 小时前
Spring 框架:配置缓存管理器、注解参数与过期时间
java·spring·缓存
Yeats_Liao2 小时前
Spring 定时任务:@Scheduled 注解四大参数解析
android·java·spring