当前位置：首页 > news >正文

Springfox + Swagger 的完整配置及同类框架对比的详细说明

news 来源：原创 2025/4/24 8:27:48

以下是 Springfox + Swagger 的完整配置及同类框架对比的详细说明：
在这里插入图片描述

一、Springfox + Swagger 配置详解

1. 添加依赖

在 pom.xml 中添加以下依赖：

<!-- Springfox Swagger 2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version> <!-- 注意版本兼容性 -->
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

2. 配置类（SwaggerConfig.java）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 指定Controller包路径.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))// 指定路径（可选，PathSelectors.any() 表示所有路径）.paths(PathSelectors.ant("/api/**")).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API文档").description("系统接口文档").version("1.0.0").contact(new Contact("开发者", "https://example.com", "dev@example.com")).license("Apache 2.0").licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html").build();}
}

3. 自定义访问地址

通过修改 application.properties 或 application.yml 自定义 Swagger UI 的访问路径：

# application.properties
springfox.documentation.swagger.v2.path=/custom-api-docs
springfox.documentation.swagger-ui.path=/custom-swagger-ui

访问地址变为：
http://localhost:8080/custom-swagger-ui

4. Controller 示例

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Api(tags = "示例接口") // 接口分组标签
public class ExampleController {@GetMapping("/hello")@ApiOperation("Hello接口")public String sayHello() {return "Hello, Swagger!";}
}

二、同类框架对比

1. Springdoc OpenAPI

特点：
- 支持 OpenAPI 3.0 标准。
- 自动扫描，无需复杂配置。
- 支持 Swagger UI 和 ReDoc。

配置示例：

<!-- pom.xml -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.12</version>
</dependency>

  # application.propertiesspringdoc.api-docs.path=/api-docsspringdoc.swagger-ui.path=/swagger-ui

访问地址：http://localhost:8080/swagger-ui

2. Swagger UI (官方版)

特点：
- 官方维护的 UI 组件。
- 需手动配置 OpenAPI 定义文件。
- 灵活适配多种后端技术。

配置示例：

<!-- pom.xml -->
<dependency><groupId>io.swagger.core.v3</groupId><artifactId>swagger-ui</artifactId><version>2.2.10</version>
</dependency>

  @SpringBootApplicationpublic class Application {public static void main(String[] args) {SpringApplication app = new SpringApplication(Application.class);// 配置 Swagger UI 路径app.setDefaultProperties(Collections.singletonMap("spring.resources.static-locations", "classpath:/META-INF/resources/"));app.run(args);}}

3. RAML

特点：
- 基于 RAML（RESTful API Modeling Language）描述接口。
- 支持自动生成文档和客户端代码。
- 适合需要详细接口规范的团队。
工具：使用 RAML Resolver 或 RAML Console 生成文档。

4. Apigee

特点：
- 企业级 API 管理平台。
- 提供完整的 API 生命周期管理（发布、监控、安全等）。
- 支持多语言文档生成。
适用场景：大型分布式系统、微服务架构。

三、功能对比表格

框架	支持协议	配置复杂度	适用场景	核心功能	访问方式
Springfox	Swagger 2.0	中等	Spring Boot 项目、简单配置	自动扫描、注解配置、支持分组	`http://localhost:8080/swagger-ui.html`
Springdoc OpenAPI	OpenAPI 3.0	低	现代 Spring Boot 项目、自动扫描	支持 OpenAPI 3、ReDoc、Swagger UI	`http://localhost:8080/swagger-ui`
Swagger UI	OpenAPI 2/3	高	需手动配置 OpenAPI 定义文件	灵活适配多种后端技术	自定义路径
RAML	RAML	高	需详细接口规范的团队	自动生成文档和客户端代码	需第三方工具支持
Apigee	多种协议	高	企业级 API 管理、复杂系统	生命周期管理、监控、安全策略	云端或私有部署