在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("[email protected]").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("[email protected]").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("[email protected]").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文档的生成,适用于现代微服务架构。

相关推荐
阮瑭雅3 分钟前
Java语言的Web安全
开发语言·后端·golang
编程乐趣10 分钟前
UnitOfWork:一个支持多数据库,工作单元模式、支持分布式事务以及支持 MySQL 多数据库/表分片的开源项目
后端
东方雴翾12 分钟前
Dart语言的3D可视化
开发语言·后端·golang
嘉然今天吃粑粑柑12 分钟前
实时通讯压缩调研
后端
雷渊15 分钟前
深入分析学习 Arthas 在项目中的应用
java·后端·面试
uhakadotcom32 分钟前
量化交易中的Barra模型:风险管理的利器
后端·面试·github
Gy-1-__34 分钟前
【springcloud】快速搭建一套分布式服务springcloudalibaba(三)
后端·spring·spring cloud
我是哪吒37 分钟前
分布式微服务系统架构第97集:JVM底层原理
后端·面试·github
小哀21 小时前
RocketMQ 5.2.0 集群Dledger的扩展调研/实践
后端·rocketmq
橘猫云计算机设计1 小时前
基于springboot科研论文检索系统的设计(源码+lw+部署文档+讲解),源码可白嫖!
java·spring boot·后端·毕业设计