Incremental updates of files managed based on git.

[shalousun]

Introduction

Currently, smart-doc pushes all content to torna each time, which leads to a large amount of data being pushed for many large projects and easily triggers the issue of excessive push size. Torna also needs to process all interfaces. Therefore, the community is exploring whether it is possible to implement incremental updates based on git management mechanisms.
Incremental updates can also solve the problem that each developer in the team may modify the smart-doc.json configuration file separately under the current version to control incremental updates, which makes collaborative management difficult.

Implementation Principle

• When pushing to torna, save the latest commit ID at the time of the push in a local file.
• The next time you push, retrieve the latest git and the ID saved from the last push, compare the changed Java classes, and when smart-doc scans the interface-related classes, if there are classes changed after the git comparison, label the data interface. Filter out the data that is not labeled during the push.
• For the situation where there are uncommitted codes locally, directly filter similar to the above according to the uncommitted Java files when pushing.

Implementation Steps

• Research related java api libraries for git, then write a demo to detect git file changes and get the object's file.
• Integrate git api into smart-doc and start implementation, discuss with community leaders during implementation.

Developers

• All developers with intention to contribute can comment on this proposal.
• Interested students can also join the official technical group of smart-doc, or search for @shalousun on WeChat to contact the author of smart-doc and participate in development.

[Fioooooooo]

大致考虑了一下，基本流程如下。但是细节还需要继续完善。

另外，如果更新了如 pathPrefix requestHeaders 等全局配置，还是需要推送全量文档。针对这种情况可以将增量推送设置为独立的参数，如 mvn -Dfile.encoding=UTF-8 smart-doc:torna-rest-incr，用户在执行命令时需要知晓当前在做什么事。

---

[shalousun]

git扫描的变更可以做成个map映射，接口构件时直接查找还是快很多，然后像

public static List<ApiParam> buildParams(String className, String pre, int level, String isRequired, boolean isResp
            , Map<String, String> registryClasses, ProjectDocConfigBuilder projectBuilder, Set<String> groupClasses
            , int pid, boolean jsonRequest, AtomicInteger atomicInteger)；

Map<String, String> registryClasses检查注册接口使用到的相关类，所以git扫描的map和这个map也是检测接口是否也要更新的原因。

总结：

1. 如果接口入参或者出参浅层次的类在git变更列表里，直接打tag。
2. 如果入口浅层的类无法判断，就需要通过上面提到的registryClasses里找，结构体嵌套比较深的情况可能用户就改的最深的那个类。
3. controller自身发生变更，例如修改注释这种，判断到方法级别获取比较难，无法判断全该controller所有方法推送也可以

[Fioooooooo]

是的，在实现时，git扫描的变更类会用map来提高检索速度。

然后controller的变更可以直接推送整个controller，一般也不会有太多接口，相比于全量推送已经节省很多了。如果想要更精准的识别到变更了哪个接口的注释，在扫描时需要记录每个文件变更的行号，然后再尝试获取每个接口的注释行号，工作量会多很多。