如果正在使用 Spring Boot 开发 RESTful API,确保其他开发人员能够轻松理解和使用 API 是至关重要的。文档提供了未来更新的参考,并帮助开发人员与 API 集成。长期以来,记录 REST API 的主要方法是使用 Swagger,这是一个开源软件框架,允许开发人员设计、构建、记录和使用 RESTful Web 服务。为了应对 Swagger 等传统 API 文档工具的代码侵入性和依赖性问题,2018 年开发了 Smart-doc 并向社区开源。
本文将探讨如何使用 Smart-doc 为 Spring Boot REST API 生成文档。
什么是 Smart-doc?
Smart-doc 是一款用于 Java 项目的接口文档生成工具。它主要通过分析和提取 Java 源代码中的注释来生成 API 文档。与 Swagger 中使用的专门注释不同,Smart-doc 扫描标准的 Java 注释,从而保持代码的简单性和非侵入性。它支持多种文档输出格式,包括 Markdown、HTML5、Postman Collection 和 OpenAPI 3.0。这种灵活性使开发人员可以根据需求选择合适的文档格式。此外,Smart-doc 还可以扫描代码以生成 JMeter 性能测试脚本。使用 Smart-doc 记录 API 的步骤
第 1 步:创建 Maven 项目
使用最新版本的 Spring Boot 创建 Maven 项目,并将 Web 依赖项添加到项目中。
第 2 步:将 Smart-doc 添加到项目中
在项目的 pom.xml
中添加 smart-doc-maven-plugin
:
<plugin>
<groupId>com.ly.smart-doc</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>[latest version]</version>
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>${project.description}</projectName>
</configuration>
</plugin>
在项目启动类所在模块的 resources
目录下创建 smart-doc.json
文件:
{
"outPath": "/path/to/userdir"
}
第 3 步:创建 REST 控制器
创建一个控制器类来处理 HTTP 请求并返回响应。以下是一个将作为 JSON 响应的控制器类:
public class User {
/**
* user id
*/
private long id;
/**
* first name
*/
private String firstName;
/**
* last name
*/
private String lastName;
/**
* email address
*/
private String email;
// Getters and Setters
}
接下来,创建一个服务类:
@Repository
public class UserRepository {
private static final Map<Long, User> users = new ConcurrentHashMap<>();
static {
User user = new User();
user.setId(1);
user.setEmail("[email protected]");
user.setFirstName("Tom");
user.setLastName("King");
users.put(1L, user);
}
public Optional<User> findById(long id) {
return Optional.ofNullable(users.get(id));
}
public void add(User user) {
users.put(user.getId(), user);
}
public List<User> getUsers() {
return new ArrayList<>(users.values());
}
public boolean delete(User user) {
return users.remove(user.getId(), user);
}
}
然后,创建 RestController
类:
@RestController
@RequestMapping("/api/v1")
public class UserController {
@Resource
private UserRepository userRepository;
@PostMapping("/users")
public ResponseResult<User> createUser(@Valid @RequestBody User user) {
userRepository.add(user);
return ResponseResult.ok(user);
}
@GetMapping("/users")
public ResponseResult<List<User>> getAllUsers() {
return ResponseResult.ok().setResultData(userRepository.getUsers());
}
@GetMapping("/users/{id}")
public ResponseResult<User> getUsersById(@PathVariable(value = "id") Long userId) {
User user = userRepository.findById(userId)
.orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
return ResponseResult.ok().setResultData(user);
}
@PutMapping("/users/{id}")
public ResponseResult<User> updateUser(@PathVariable(value = "id") Long userId, @Valid @RequestBody User userDetails) {
User user = userRepository.findById(userId)
.orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
user.setEmail(userDetails.getEmail());
user.setLastName(userDetails.getLastName());
user.setFirstName(userDetails.getFirstName());
userRepository.add(user);
return ResponseResult.ok().setResultData(user);
}
@DeleteMapping("/users/{id}")
public ResponseResult<Boolean> deleteUser(@PathVariable(value = "id") Long userId) {
User user = userRepository.findById(userId)
.orElseThrow(() -> new ResourceNotFoundException("User not found on :: " + userId));
return ResponseResult.ok().setResultData(userRepository.delete(user));
}
}
第 4 步:生成文档
可以使用 IntelliJ IDEA 中的 Smart-doc 插件生成所需的文档,例如 OpenAPI、Markdown 等。
也可以使用 Maven 命令生成:
mvn smart-doc:html
mvn smart-doc:markdown
mvn smart-doc:adoc
mvn smart-doc:postman
mvn smart-doc:openapi
第 5 步:导入到 Postman
使用 Smart-doc 生成 Postman.json
后,可将其导入到 Postman 中查看效果。由于 Smart-doc 支持多种格式的文档,可以选择生成 OpenAPI,随后使用 Swagger UI 进行展示,或将其导入专业的 API 文档系统中。
结论
从前面的例子可以看出,Smart-doc 通过扫描代码中的标准 Java 注释来生成文档,无需像 Swagger 那样使用专门的注释,从而保持了代码的简洁性和非侵入性,同时不会影响服务 Jar 包的大小。它支持多种文档输出格式,包括 Markdown、HTML5、Postman Collection 和 OpenAPI 3.0,这种灵活性使得开发者可以根据需求选择合适的文档格式进行输出。此外,Smart-doc 提供的 Maven 或 Gradle 插件也方便将文档生成集成到 DevOps 流水线中。
虽然 Swagger 具备更强大的 UI 功能,并对 Spring Boot Webflux 提供了更好的支持,但 Smart-doc 的简单性和灵活性依然使其成为一个优秀的选择。
原文链接:Documenting a Spring REST API Using Smart-doc
Keyword: api接口