如何在不同环境下控制Springfox API文档的开放

2022-11-18 16:07:01

在Spring Boot应用中控制Springfox API文档

在构建REST API时，API文档对于理解和使用API至关重要。Springfox提供了Swagger 和OpenAPI 工具，可以自动生成易于理解的API文档。然而，在生产环境中，公开API文档可能会带来安全隐患。因此，了解如何控制Springfox API文档至关重要。

一、禁用Springfox API文档

禁用Springfox API文档非常简单。首先，添加Springfox启动器依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

然后，在application.properties文件中添加以下配置：

springfox.documentation.enabled=false

二、区分生产环境和开发环境

在不同的环境（如开发和生产）中控制API文档非常重要。有几种方法可以区分这些环境：

端口： 使用不同的端口（如开发为8080，生产为80）
域名： 使用不同的域名（如dev.example.com和www.example.com）
环境变量： 使用不同的环境变量（如SPRING_PROFILES_ACTIVE=dev和SPRING_PROFILES_ACTIVE=prod）

三、通过开关控制Springfox API文档

使用开关控制Springfox API文档提供了一种灵活的方式来管理文档的可用性。要实现这一点：

在application.properties文件中添加配置：

springfox.documentation.enabled=${springfox.documentation.enabled}

创建application-dev.properties和application-prod.properties配置文件，并设置相应的文档启用值：

# application-dev.properties
springfox.documentation.enabled=true

# application-prod.properties
springfox.documentation.enabled=false

四、使用代码示例

以下代码示例演示了如何通过开关控制Springfox API文档：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Springfox API文档")
                .description("Springfox API文档，用于生成API文档，方便开发人员理解和使用我们的API。")
                .termsOfServiceUrl("http://www.example.com/terms")
                .contact(new Contact("John Doe", "http://www.example.com/contact", "john.doe@example.com"))
                .version("1.0")
                .build();
    }
}