SpringBoot集成Smart-doc生成接口文档，比swg简单

小半 • 2023年2月16日上午10:14 • 技术随笔 • 阅读 337

1.Smart-doc概念：

一个 java restful api 文档生成工具，不用像Swagger一样写大量注解，完全基于接口源码分析来生成接口文档，但是需要按照 java的标准注释写

2.简单使用

2.1导入依赖

<!--导入Smart-doc依赖-->
        <dependency>
            <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc</artifactId>
            <version>1.8.1</version>
            <scope>test</scope>
        </dependency>

2.2测试代码

 @Test
    public void testBuilderControllersApi() {
        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
        //源码---String HTML_DOC_OUT_PATH = "src/main/resources/static/doc";
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);

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

        //设置错误错列表，遍历自己的错误码设置给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);
    }

运行后会在对应目录生成htmlAPI接口文档

2.3检查控制层和实体类上的注释

/**
 * 用户控制类
 */
@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {

    /**
     * 获取用户数据
     * @return
     */
    @GetMapping("/getUser")
    public User getUser() {
        return new User("zhangxi","123");
    }

    /**
     * 添加用户信息
     * @param user
     * @return
     */
    @PostMapping("/setUser")
    public User setUser(User user)
    {
        return user;
    }
}

@ApiModel("User用户实体类")
public class User {
    /**
     * 用户名
     */
    @ApiModelProperty("用户名")
    private String username;

    /**
     * 密码
     */
    @ApiModelProperty("密码")
    private String password;