smart-doc接口文档生成工具

java后端指南

发布于 2021-08-13 15:13:41

1.4K1

发布于 2021-08-13 15:13:41

Part1文章首推

Part2今日主题:smart-doc接口文档生成工具

这个一个接口生成文档工具，之前我也有推荐swagger这款工具，但是这款工具在生产环境中却不怎么用，对代码的侵入性太高了，现在来介绍一下smart-doc这款接口文档工具吧，他可以识别javadoc注释然后生成文档，也就是说只要你采用正常的注释就好了。

1依赖

首先我们需要引入依赖就好了

   <dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>1.8.1</version>
    <scope>test</scope>
</dependency>

2实现

我们可以写一个实体类来测试，只要这样写注释就好了

public class User {
    /**
     * 用户id
     */
    private String userId;
    /**
     * 用户名
     */
    private String userName;
    /**
     * 密码
     */
    private String password;
    /**
     * 年龄
     */
    private String age;

    public User() {
    }

    public User(String userId, String userName, String password, String age) {
        this.userId = userId;
        this.userName = userName;
        this.password = password;
        this.age = age;
    }

    public String getUserId() {
        return userId;
    }

    public void setUserId(String userId) {
        this.userId = userId;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getAge() {
        return age;
    }

    public void setAge(String age) {
        this.age = age;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

写两个控制类

/**
 * 用户
 */
@RestController
public class UserAction {
    /**
     * 用户登录接口
     * @author xujp
     * @param userName 用户名
     * @param password 密码
     * @return
     * @date 2021/7/31 15:31
     */
    @RequestMapping("/login")
    public User login(String userName,String password){
        return new User("1",userName,password,"20");
    }
}

/**
 * 测试
 */
@RestController
public class TestAction {
    /**
     * 测试用的接口
     * @param str 字符串
     * @return 12345
     */
    @RequestMapping("/test")
    public String test(String str){
        return str;
    }
}

这样我们就写好了两个控制类

现在我们去写一个文档生成工具

/**
 * @author : xujp0818
 * @date : 2021/7/31 15:28
 */
public class DocUtil {
    private static void createDoc(){
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //当把AllInOne设置为true时，Smart-doc将会把所有接口生成到一个Markdown、HHTML或者AsciiDoc中
        config.setAllInOne(true);

        //HTML5文档，建议直接放到src/main/resources/static/doc下，Smart-doc提供一个配置常量HTML_DOC_OUT_PATH
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);

        // 设置接口包扫描路径过滤，如果不配置则Smart-doc默认扫描所有的接口类
        // 配置多个包名有英文逗号隔开
        config.setPackageFilters("com.example.action.UserAction,com.example.action.TestAction");

        //设置错误错列表，遍历自己的错误码设置给Smart-doc即可
        List<ApiErrorCode> errorCodeList = new ArrayList<>();
        for (HttpCodeEnum codeEnum : HttpCodeEnum.values()) {
            ApiErrorCode errorCode = new ApiErrorCode();
            errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getMessage());
            errorCodeList.add(errorCode);
        }

        //不需要显示错误码,则可以不用设置错误码。
        config.setErrorCodes(errorCodeList);
        //生成Markdown文件
        HtmlApiDocBuilder.buildApiDoc(config);
    }

    public static void main(String[] args) {
        createDoc();
    }
}

我们可以直接访问html,就可以了