smart-doc加Torna实现文档管理

介绍

smart-doc + Torna 组成行业领先的文档生成和管理解决方案，使用smart-doc无侵入完成Java源代码和注释提取生成API文档，自动将文档推送到Torna企业级接口文档管理平台。

使用

配置数据库

mysql.sql

安装Torna

docker pull tanghc2020/torna:1.20.0

wget https://gitee.com/durcframework/torna/raw/master/install/application.properties

下载配置文件并修改数据库配置

# Server port
server.port=7700

# MySQL host
mysql.host=ip:port
# Schema name
mysql.schema=torna
# Make sure the account can run CREATE/ALTER SQL
mysql.username=xxx
mysql.password=xxx

创建容器

docker run -d --name torna -p 7700:7700 -e JAVA_OPTS="-server -Xms128m -Xmx128m" -v /root/test_torna/application.properties:/torna/config/application.properties tanghc2020/torna:1.20.0

注意，要开启防火墙对端口号的限制，访问地址 http://ip:7700 初始账号 admin/123456

项目中使用smart-doc

在项目中创建 src/main/resources/smart-doc.json

{
  "isStrict": false, //是否开启严格模式
  "packageFilters": "",//controller包过滤，多个包用英文逗号隔开
  "projectName": "spring_xxx",//配置自己的项目名称
  "appToken": "", //torna平台appToken,@since 2.0.9
  "openUrl": "http://ip:7700/api",//torna平台地址，填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna测试环境
  "replace": true //推送torna时替换旧的文档
}

实际使用时将注释去掉，appToken从如下页面中获取

<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>spring-messagequeue</projectName>
      <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
      <excludes>
          <!--格式为：groupId:artifactId;参考如下-->
          <!--也可以支持正则式如：com.alibaba:.* -->
          <exclude>com.alibaba:fastjson</exclude>
      </excludes>
      <!--includes配置用于配置加载外部依赖源码,配置后插件会按照配置项加载外部源代码而不是自动加载所有，因此使用时需要注意-->
      <!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
      <includes>
          <!-- 使用了mybatis-plus的Page分页需要include所使用的源码包 -->
          <include>com.baomidou:mybatis-plus-extension</include>
          <!-- 使用了mybatis-plus的IPage分页需要include mybatis-plus-core-->
          <include>com.baomidou:mybatis-plus-core</include>
          <!-- 如果配置了includes的情况下， 使用了jpa的分页需要include所使用的源码包 -->
          <include>org.springframework.data:spring-data-commons</include>
      </includes>
  </configuration>
  <executions>
      <execution>
          <!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
          <phase>compile</phase>
          <goals>
              <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
              <!--<goal>markdown</goal>-->
          </goals>
      </execution>
  </executions>
</plugin>

推送到Torna平台

代码中添加注释

import com.imooc.messagequeue.entity.CommonResult;
import com.imooc.messagequeue.entity.Product;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.validation.Valid;
import java.util.ArrayList;
import java.util.List;

/**
 * 商品模块
 *
 * @author szz 2023/3/1
 */
@RestController
@RequestMapping("/product")
public class TestSmartDocController {

    /**
     * 创建商品
     *
     * @param product 商品创建请求
     * @return
     */
    @PostMapping("/createProduct")
    public CommonResult<Boolean> createProduct(@RequestBody @Valid Product product) {
        return CommonResult.success(true);
    }

    /**
     * 根据商品名称查询商品
     *
     * @param productName 商品名称
     * @return
     */
    @GetMapping("/searchProduct")
    public CommonResult<List<Product>> searchProduct(@RequestParam String productName) {
        return CommonResult.success(new ArrayList<>());
    }

    /**
     * 创建商品
     *
     * @param product 商品创建请求
     * @return
     * @ignore
     */
    @PostMapping("/createProduct2")
    public Product createProduct2(@RequestBody @Valid Product product) {
        return product;
    }
}

/**
 * 统一响应结果
 */
public class CommonResult<T> {

    /**
     * 错误码 0表示成功
     */
    private String errCode;
    /**
     * 错误信息
     */
    private String errMsg;
    /**
     * 实际返回数据
     */
    private T data;

    private CommonResult(String errCode, String errMsg, T data) {
        this.errCode = errCode;
        this.errMsg = errMsg;
        this.data = data;
    }

    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<>("0", null, data);
    }

    public static <T> CommonResult<T> fail(String errCode, String errMsg) {
        return new CommonResult<>(errCode, errMsg, null);
    }
}

import lombok.Data;

import javax.validation.Valid;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotEmpty;
import java.math.BigDecimal;
import java.util.List;

/**
 * 商品实体类
 */
@Data
public class Product {

    /**
     * 商品名称
     */
    @NotBlank(message = "商品不能不能为空")
    private String productName;
    /**
     * 商品描述
     * @mock 测试描述
     */
    private String productDesc;
    /**
     * 商品价格
     */
    private BigDecimal price;

    /**
     * 商品SKU列表
     */
    @NotEmpty(message = "商品不能不能为空")
    @Valid
    private List<Sku> skus;

    /**
     * 商品SKU详情
     */
    @Data
    public static class Sku {

        /**
         * sku描述
         */
        private String skuDesc;
        /**
         * sku价格
         */
        private String price;
    }
}

主要tag

• @param 方法参数
• @mock smart-doc自定义tag，表示字段示例值
• @ignore smart-doc自定义tag，在类或方法注释中使用，表示忽略此类或方法，对于属性，建议使用Json转换框架的注解(如@JsonIgnore)去忽略
• @auther 作者信息

支持 JSR-303 参数验证规范，如@NotBlank,@NotEmpty

页面效果

多模块构建

• parent
  • common(存放model类，被其它模块依赖使用)
  • spring-boot-web(一个web测试模块，依赖common)

直接在web模块中添加插件配置及smart-doc.json配置，依赖的模块需要先install。

参考

Torna官网
Torna开发文档
Torna源码仓库-gitee
smart-doc源码仓库
smart-doc官网文档