SpringBoot 引入 smart-doc 接口文档管理插件，以及统一接口返回，最后推送到 Torna，进行统一管理

最近在将多个服务端项目的接口进行整合管理，原本使用的是Swagger接口文档管理插件，网上搜了一下类似的插件，发现这个smart-doc插件，似乎挺简约优雅的，而且还可以推送接口文档到Torna，进行统一管理，这功能相当不错。

smart-doc 官网文档（https://smart-doc-group.github.io/）

smart-doc 发行版本：https://github.com/smart-doc-group/smart-doc/releases

一、SpringBoot项目整合smart-doc接口文档管理插件

1、引入 smart-doc 插件

pom.xml

<!-- 引入 smart-doc 插件 -->
<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.6.4</version>
    <configuration>
        <!-- 指定生成文档使用的配置文件 -->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <projectName>欢迎使用 Smart-Doc~</projectName>
    </configuration>
</plugin>
<!-- / 引入 smart-doc 插件 -->

2、新建接口文档配置文件

smart-doc.json

{
   
   
  "serverUrl": "http://127.0.0.1:8091",
  "isStrict": false,
  "allInOne": true,
  "createDebugPage": true,
  "style":"xt256",
  "allInOneDocFileName":"index.html",
  "outPath": "src/main/resources/static/doc",
  "packageFilters": "org.example.controller.*",
  "style": "mono-blue",
  "projectName": "欢迎使用 smart-doc ~"
}

3、新建静态资源配置文件

StaticResourceConfig.java

package org.example.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class StaticResourceConfig extends WebMvcConfigurationSupport {
   
   

    @Value("${system.upload-file-path}")
    private String UploadFilePath;

    public void addResourceHandlers(ResourceHandlerRegistry registry) {
   
   
        /* ^ 配置 static 静态资源路径 */
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        /* / 配置 static 静态资源路径 */

        /* ^ 配置 文件上传 资源路径 */
        registry.addResourceHandler("/UploadFilePath/**").addResourceLocations("file:" + UploadFilePath);
        /* / 配置 文件上传 资源路径 */

        /* ^ 配置 smart-doc 资源路径 */
        registry.addResourceHandler("/doc/**").addResourceLocations("classpath:/static/doc/");
        /* / 配置 smart-doc 资源路径 */
    }
}

4、若有使用拦截器等等，需要放行"/doc/**"请求路径，然后APP配置文件也不用配置啥的

application.yml

server:
  port: 8091

spring:
  application:
    name: "帅龍之龍"

# 自定义配置
system:
  # 配置文件上传路径
  upload-file-path: "C:/UploadFilePath/"

二、统一接口返回

1、新建统一接口返回类文件

Result.java

package org.example.pojo.response;

public class Result <T> {
   
   

    /**
     * 响应状态
     * @since 1.0.0
     */
    private boolean success = true;

    /**
     * 错误码
     * @since 1.0.0
     */
    private int errno = 0;

    /**
     * 响应消息
     * @since 1.0.0
     */
    private String msg;

    /**
     * 响应数据
     * @since 1.0.0
     */
    private T data;

    public Result(boolean success, String msg) {
   
   
        this.success = success;
        this.msg = msg;
    }

    public Result(boolean success, String msg, T data) {
   
   
        this.success = success;
        this.msg = msg;
        this.data = data;
    }

    public Result(boolean success, int errno, String msg) {
   
   
        this.success = success;
        this.errno = errno;
        this.msg = msg;
    }

    public Result(boolean success, int errno, String msg, T data) {
   
   
        this.success = success;
        this.errno = errno;
        this.msg = msg;
        this.data = data;
    }

    public boolean getSuccess() {
   
   
        return success;
    }

    public void setSuccess(boolean success) {
   
   
        this.success = success;
    }

    public int getErrno() {
   
   
        return errno;
    }

    public void setErrno(int errno) {
   
   
        this.errno = errno;
    }

    public String getMsg() {
   
   
        return msg;
    }

    public void setMsg(String msg) {
   
   
        this.msg = msg;
    }

    public T getData() {
   
   
        return data;
    }

    public void setData(T data) {
   
   
        this.data = data;
    }

    @Override
    public String toString() {
   
   
        return "Result{" +
                "success=" + success +
                ", msg='" + msg + '\'' +
                ", data=" + data +
                '}';
    }
}

2、新建用户视图类

User.java

package org.example.pojo.entity;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;

import java.util.Date;

@Data
@ToString
@AllArgsConstructor
@NoArgsConstructor
public class User {
   
   

    /**
     * 用户ID
     */
    private Long id;

    /**
     * 用户名
     */
    private String username;

    /**
     * 用户密码
     */
    private String password;

    /**
     * 用户地址
     */
    private String address;

    /**
     * 用户年龄
     */
    private int userAge;

    /**
     * 手机号
     */
    private String phone;

    /**
     * 创建时间
     */
    private Date createTime;
}

3、新建用户信息管理控制器

UserManageController.java

package org.example.controller;

import lombok.extern.slf4j.Slf4j;
import org.example.pojo.entity.User;
import org.example.pojo.response.Result;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.FileNotFoundException;
import java.io.IOException;

/**
 * 用户管理模块
 */
@Slf4j
@RestController
@RequestMapping(value = "/v1/api")
public class UserManageController {
   
   

    @Value("${system.upload-file-path}")
    private String UploadFilePath;

    /**
     * 根据用户ID查询用户信息
     * @author 帅龍之龍
     * @param token 鉴权凭据
     * @param userId 用户ID 示例:10001
     * @return
     */
    @GetMapping(value = "getUserById")
    @CrossOrigin
    @ResponseBody
    public Result getUserById(@RequestHeader("auth-token") String token,
                              @RequestParam(value = "userId", defaultValue = "10001") Long userId) {
   
   
        log.info(token);
        User user = new User();
        user.setId(userId);
        user.setUsername("帅龍之龍");
        user.setPassword("123456");
        user.setUserAge(25);
        user.setPhone("134****3051");
        user.setCreateTime("2023-3-14 15:05:44");
        user.setAddress("地球村");
        return new Result(true, "getUserById 成功", user);
    }

    /**
     * 保存用户信息
     * @author 帅龍之龍
     * @param token 鉴权凭据
     * @param user 用户对象
     * @return
     */
    @PostMapping(value = "saveUser")
    @CrossOrigin
    public Result saveUser(@RequestHeader("auth-token") String token,
                           @RequestBody User user) {
   
   
        log.info(token, user.toString());
        return new Result(true, "saveUser 成功", user);
    }

    /**
     * 单文件上传
     * @author 帅龍之龍
     * @param token 鉴权凭据
     * @param file 文件
     * @return
     */
    @ResponseBody
    @PostMapping(value = "singleFileUploadAction")
    @CrossOrigin
    public Result singleFileUploadAction(@RequestHeader("auth-token") String token,
                                         @RequestParam MultipartFile file) {
   
   
        log.info(token);
        try {
   
   
            String originFileName = file.getOriginalFilename(); // 原文件名，如：hello.pdf
            String destFileName = UploadFilePath + File.separator + originFileName; // 完整文件名 = 存储路径 + 原文件名

            // 复制文件到指定目录
            File destFile = new File(destFileName);
            destFile.getParentFile().mkdirs();
            file.transferTo(destFile);

            // 文件链接
            String url = "http://localhost:8091/UploadFilePath/" + originFileName;

            return new Result(true, "singleFileUploadAction 成功", url);
        } catch (FileNotFoundException e) {
   
   
            e.printStackTrace();
            return new Result(false, "singleFileUploadAction 失败", e.getMessage());
        } catch (IOException e) {
   
   
            e.printStackTrace();
            return new Result(false, "singleFileUploadAction 失败", e.getMessage());
        }
    }
}

三、smart-doc页面效果

四、如果你觉得还不够，还想统一管理所有接口文档，那就可以推送到 Torna 接口文档管理系统进行统一管理，不妨试试。

首先是在 Torna 官网（https://torna.cn/），下载源码，源码有前端Vue项目，后端SpringBoot项目，数据库文件等。

本地启动好了 Torna 后，按照官网上指导说明，登录 Torna，创建应用啥的，然后在自己项目的 smart-doc.json 配置文件加入相关键值对，如下面所示。

"appToken": "80820f95cf4649609b25fd440a9f9446",
"openUrl": "http://127.0.0.1:7700/api",
"debugEnvName": "调试环境",
"debugEnvUrl": "http://127.0.0.1:8091",
"replace": true

Smart-Doc推送到 Torna 详细说明（https://smart-doc-group.github.io/#/zh-cn/?id=smart-doc）