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

<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 {

    @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的相关设置：

# application.yml
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-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文档的生成，适用于现代微服务架构。