原文地址：https://dev.to/smartyansh/introduction-to-springfox-48ng 作者：Anshul Bansal
Spring 是一个非常流行的 JEE 框架，用于创建 Web 应用程序。我们经常使用 Spring 技术来暴露 API 给第三方集成。这时，我们的 API 需要详细的规范来帮助轻松集成。
在本教程中，我们将探索 Springfox Java 库来为 Spring 应用程序生成基于 Swagger 的 API 规范。
Springfox
Springfox 是一组 Java 库，它演变自 swagger-springmvc 项目。它自动生成使用 Spring 框架实现的 JSON API 的规范。同时，它提供与 API 交互的 Swagger UI 集成的库。
Springfox 在运行时检查 Spring 应用程序并根据配置和注解生成 API 规范。
让我们探索 Swagger 2 与 Spring REST API 的集成。同时，我们也会接触基本配置。
设置
让我们将最新的 springfox-swagger2 Maven 依赖项添加到我们的 Spring Boot 应用程序中：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>类似地，我们可以将 springfox-swagger2 依赖项添加到基于 Gradle 的 Spring 项目中：
compile "io.springfox:springfox-swagger2:2.9.2"@EnableSwagger2
现在我们已经设置了 Springfox 依赖项。让我们启用 Swagger 2 来生成 API 规范。
为此，我们将在应用程序的主类中添加@EnableSwagger2 注解：
@EnableSwagger2
@SpringBootApplication
public class SpringfoxApplication {
public static void main(String[] args) {
SpringApplication.run(SpringfoxApplication.class, args);
}
}使用 Maven 命令启动应用程序：
mvn spring-boot:run我们可以在 localhost:8080/v2/api-docs 以 JSON 格式访问规范：
Swagger UI
JSON 格式的 API 规范不可读，难以遵循。因此，我们需要 UI 支持，以便于与 API 规范进行交互。
因此，通过将 springfox-swagger-ui 依赖项添加到 pom.xml 中，将 Swagger UI 集成到我们的应用程序中：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>然后，我们将重启应用程序，并在 localhost:8080/swagger-ui.html 访问 Swagger UI:
Spring REST API
让我们探索 Swagger 2 与 Spring REST API 的集成。
首先，让我们创建一个名为 User 的实体：
@Entity
public class User{
@Id
private Long id;
private String firstName;
private int age;
private String email;
//getters and setters
}然后，我们将创建 UserRepository 在 User 实体上添加 CRUD 操作：
@Repository
public interface UserRepository extends CrudRepository<User, Long> {
}现在，我们将创建 UserController 用于 REST API:
@Controller
@RequestMapping(value = "/api/user", produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController {
@Autowired
private UserRepository userRepository;
@PostMapping
public @ResponseBody ResponseEntity<User> createUser(@RequestBody User user) {
userRepository.save(user);
return new ResponseEntity<>(user, HttpStatus.OK);
}
@GetMapping
public @ResponseBody ResponseEntity<User> getUser(@RequestParam Long id) {
Optional<User> user = userRepository.findById(id);
return new ResponseEntity<>(user.get(), HttpStatus.OK);
}
}现在我们已经有了实体、存储库和控制器。让我们将所有内容集成到主类中：
@SpringBootApplication
@EnableSwagger2
public class SpringfoxApplication {
// ...
}然后，我们将重启应用程序以查看更改：
如上图，我们可以看到为 UserController API 生成了规范。
配置
让我们探索 Springfox 配置的基础知识。
我们可以使用 Docket 类配置 API 规范。为此，我们应该在主类中创建一个注册为 bean 的方法并返回一个 Docket 实例。
在 SpringfoxApplication 中创建一个 springfoxAppInfo bean 方法：
public class SpringfoxApplication {
//...
@Bean
public Docket springfoxAppInfo() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("Springfox-api")
.select()
.paths(paths())
.build();
.apiInfo(apiInfo());
}
private Predicate<String> paths() {
return regex("/api/.*");
}
private ApiInfo apiInfo() {
return new ApiInfo(
"Springfox API specification",
"Spring REST APIs",
"",
"",
null,
"License of API",
"API license URL",
Collections.emptyList());
}
}在这里，我们更改了一些属性，如 groupName 和 apiInfo。另外，我们将 API 规范限制为 api URI 路径。
让我们重启应用程序并查看规范中的差异：
这里，我们可以观察到 API 信息已更改。另外，根据提到的 /api URI 路径，规范仅针对 UserController 可用。
总结
在本文中，我们探索了Springfox套件的库，用于生成使用Spring框架实现的API的规范。首先，我们创建了一个Spring Boot应用程序，并集成了Swagger 2 API来创建规范。此外，我们还看到了与Swagger UI的集成。然后，我们研究了将Swagger集成到Spring REST API中的方法。最后，我们简要介绍了Swagger UI配置的基础知识。
请在Github上找到完整的代码实现。
使用 Apifox 管理 API 文档
Swagger 管理接口有时很不方便，缺乏团队间的分享协作，所以我更推荐使用 Apifox。
Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http(s)、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。在开发完接口后，可以通过 Apifox 的 IDEA 插件一键生成接口文档，多端同步，非常方便测试和维护。
将 Swagger 导出为 JSON
如下图所示，选择“Convert and save as JSON”，将 Swagger 文档导出为 JSON 文件。
将 Swagger 文件导入 Apifox
打开 Apifox，创建一个项目后，选择“项目设置->导入数据->OpenAPI/Swagger->文件导入”，将已导出的 Swagger 格式的 JSON 文件导入即可。
导入时，会有预览，可以选择导入全部，也可以选择性的导入接口。
导入成功之后，就可以选择一个环境来测试接口。如下图所示，接口成功返回数据：
知识扩展：