使用 Smart-doc 生成 Spring REST API 文档

如果正在使用 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("123@gmail.com");
        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