SpringBoot+SmartDoc - unknown

SpringBoot+SmartDoc

简介

SmartDoc是一款支持Java Rest Api 、Java WebSocket、Apache Dubbo RPC和gRPC接口文档生成的工具。它对环境的需求是Mavne3.8+以及JDK1.8+。

SmartDoc率先提出了基于java泛型定义来推导接口文档的概念，它完全依赖于接口的源代码进行分析和生成文档，无需像Swagger那样在业务代码中添加任何注解，只需按照JavaDoc的标准进行编写注释，SmartDoc即可生成简洁明了的Markdown、HTML5、Pastman Collection2.0+和OpenAI3.0格式的文档。

本文是SpringBoot单模块基于官方文档Mavne插件的形式使用。

官方文档中还表明了可以是用Maven依赖的方式以及Spring Cloud的方式使用。

Mavne插件

在SpringBoot的启动类中的pom.xml加入依赖。

• Mavne插件的版本是和Mavne依赖版本是一致的，笔者是在Mavne仓库中com.ly.smart-doc查看Maven依赖的版本得知插件的版本的。

 <plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<!-- -->
<plugin><groupId>com.ly.smart-doc</groupId><artifactId>smart-doc-maven-plugin</artifactId><version>3.1.2</version><configuration><configFile>./src/main/resources/smart-doc.json</configFile><projectName>${project.description}</projectName><includes><!-- 加载第三方包的模板 --><!-- <include>com.baomidou:mybatis-plus-extension</include>  --></includes></configuration><executions><execution><!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
<!--                        <phase>compile</phase>-->
<!--                        <goals>-->
<!--                            &lt;!&ndash;smart-doc提供了html、openapi、markdown等goal，可按需配置&ndash;&gt;-->
<!--                            <goal>markdown</goal>-->
<!--                        </goals>--></execution></executions>
</plugin>

配置文件

在SpringBoot的启动类中的resources文件下建立一个smart-doc.json文件

{"outPath": "./src/doc" //文档输出位置,更多配置文件请查看官方文档
}

SpringBoot文件

在SpringBoot中，所有的入参和返回参数请使用对象的方式。

/*** <P>统一结果返回封装</P>* @param <T>*/
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> implements Serializable {@Serialprivate static final long serialVersionUID = 4105682081252678513L;/*** <P>提示消息</P>*/private String message;/*** <P>返回状态码</P>*/private int status;/*** <P>数据封装</P>*/private T data;/*** <P>数据字典</P>*/private Object dict;}

Controller

/*** <P>用户认证</P>* @author unknown* @since 2025/11/18 11:41*/
@RestController
@RequestMapping("/auth")
@RequiredArgsConstructor
public class AuthController {
/*** <P>管理员注册</P>** @param manageRegister 管理员信息* @return Result*/
@PostMapping("manage-register")
public Result<?> manageRegister(@RequestBody @Validated ManageRegister manageRegister) throws Exception {LoginToken loginToken = manageService.manageRegister(manageRegister);return ResultBuilder.successResult(loginToken);
}/*** <P>管理员登录</P>** @param phone    手机号* @param password 密码* @return Result*/
@PostMapping("manage-login")
public Result<?> manageLogin(@RequestParam("phone") @NotNull String phone,@RequestParam("password") @NotNull String password) throws Exception {LoginToken loginToken = manageService.manageLogin(phone, password);return ResultBuilder.successResult(loginToken);
}
}

生成文档

• 在Mavne插件中选择一种格式来生成文档，文档的位置在resources文件下smart-doc.json文件中有定义

查看文档

• 生成的文档内容如下，我选择的是markdow格式，因为笔记也是此格式，方便嵌入文档。

<P>管理员注册</P>

URL: /auth/manage-register

Type: POST

Author: unknown

Content-Type: application/json

Description:

管理员注册

Body-parameters:

Parameter	Type	Required	Description	Since	Example
userName	string	true	名称	-
phone	string	true	手机号	-
password	string	true	密码	-

Request-example:

curl -X POST -H "Content-Type: application/json" -i '/auth/manage-register' --data '{"userName": "","phone": "","password": ""
}'

Response-fields:

Field	Type	Description	Since	Example
message	string	提示消息	-
status	int32	返回状态码	-	0
data	object	数据封装	-
dict	object	数据字典	-

Response-example:

{"message": "","status": 0,"data": {},"dict": {"object": "any object"}
}

<P>管理员登录</P>

URL: /auth/manage-login

Type: POST

Author: unknown

Content-Type: application/x-www-form-urlencoded

Description:

管理员登录

Query-parameters:

Parameter	Type	Required	Description	Since	Example
phone	string	true	手机号	-
password	string	true	密码	-

Request-example:

curl -X POST -i '/auth/manage-login?phone=&password='

Response-fields:

Field	Type	Description	Since	Example
message	string	提示消息	-
status	int32	返回状态码	-	0
data	object	数据封装	-
dict	object	数据字典	-

Response-example:

{"message": "","status": 0,"data": {},"dict": {"object": "any object"}
}