Spring Boot的自定义OpenApi文档

基础概念

OpenAPI（以前称为Swagger）是一种用于描述、生成、消费和可视化RESTful Web服务的机器可读接口文件格式。Spring Boot通过集成Springfox或Springdoc等库，可以轻松生成OpenAPI文档。

类型

Springfox：较早的库，通过注解和配置生成OpenAPI文档。
Springdoc：较新的库，更简单易用，支持Spring Boot 2.x。

应用场景

API文档管理：为开发者提供详细的API文档。
前后端分离：前端开发者可以通过OpenAPI文档了解后端API的详细信息。
自动化测试：通过生成的文档进行自动化测试。

遇到的问题及解决方法

问题1：生成的OpenAPI文档不准确或不完整

原因：可能是由于注解使用不当或配置错误。 解决方法：

确保所有API接口都使用了正确的注解，如@RestController、@RequestMapping等。
检查配置文件，确保Springfox或Springdoc的配置正确。

示例代码（Springfox）：

import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

示例代码（Springdoc）：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringdocConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Custom API Title")
                        .version("1.0.0")
                        .description("Custom API Description"));
    }
}

问题2：生成的OpenAPI文档无法访问

原因：可能是由于配置错误或端口冲突。 解决方法：

确保Spring Boot应用的端口配置正确。
检查是否有防火墙或安全组阻止了访问。

示例配置：

server:
  port: 8080

问题3：生成的OpenAPI文档样式不一致

原因：可能是由于使用了不同的库或版本不一致。 解决方法：

确保使用的Springfox或Springdoc版本一致。
可以自定义样式，通过配置文件或代码进行样式调整。

示例配置（Springfox）：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build()
            .pathMapping("/")
            .directModelSubstitute(LocalDate.class, String.class)
            .genericModelSubstitutes(ResponseEntity.class)
            .useDefaultResponseMessages(false);
}