久久97久久99久久综合,国产精品久久久久久网站,伊人五月天婷婷

第 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