SpringBoot+SmartDoc

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 {

    @Serial
    private 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"
  }
}