基于REST API无侵入的静态接口文档生成工具

项目是基于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类上时，生成文档会忽略该类，
  用在方法上，忽略该方法
• 更多内容查看这里