專案是基於SpringBoot開發

好處

• 使用的是註釋（非註解），對程式碼無侵入
• 生成的文件是靜態文件，減小服務壓力

依賴

• pom.xml中新增

<!--介面文件生成-->
<dependency>
    <groupId>io.github.yedaxia</groupId>
    <artifactId>japidocs</artifactId>
    <version>1.4.4</version>
    <!--scope為test時，只在測試環境有效，即打包為jar時不包含該依賴-->
    <scope>test</scope>
</dependency>
 

使用

• 在test目錄中使用

import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class ApplicationTests {
    @Test
    void createApiDoc() {
        DocsConfig config = new DocsConfig();
        config.setProjectPath("D:/api-doc-demo"); //專案路徑
        config.setProjectName("介面文件生成案例"); //專案名稱
        config.setApiVersion("V1.0"); //介面版本
        config.setDocsPath("D:/api-doc"); //生成介面文件的位置
        config.setAutoGenerate(Boolean.TRUE);  //自動配置
        Docs.buildHtmlDocs(config);
    }
}
 

準則

• japidocs是基於JAVA DOC生成的文件
• japidocs會對原始碼中的Controller進行分析
• 通過分析介面方法上的註釋、方法名、引數、返回值等來生成對應文件

基於以上原因，我們在編寫介面時儘量使註釋變得易於理解

/**
 * 使用者介面（這裡的註釋最終變成文件的選單，沒有則使用Controller類名）
 */
@RequestMapping("/user")
@RestController
public class UserController {

    /**
     * 通過使用者名稱稱獲取使用者列表（這裡的註釋最終變成介面的標題）
     * @param name 使用者名稱稱（這裡的註釋最終變成介面引數的描述）
     */
    @GetMapping("/list")
    public List<User> list(@RequestParam String name) {
        return null;
    }

    /**
     * 儲存使用者
     * @param user
     */
    @PostMapping("/save")
    public Msg<Boolean> saveUser(@RequestBody User user) {
        return null;
    }

    /**
     * 通過id刪除使用者
     * @param userId 使用者id
     */
    @PostMapping("/delete")
    public ApiResult deleteUser(@RequestParam Long userId) {
        return null;
    }
}
 

相關注解使用

• @Ignore 註解，該註解全限定名為
  jdk.nashorn.internal.ir.annotations.Ignore，
  是jdk內部註解，用在Controller類上時，生成文件會忽略該類，
  用在方法上，忽略該方法
• 更多內容檢視這裡