使用smart-doc ，放弃japidocs，更放弃 swagger

Posted 2021-06-30 正怒月神

众所周知（真不是人云亦云）

swagger强大吗？强大的。但是代码侵入性太强了！

japidocs ,没有代码入侵问题，也很好！

但是有个bug！没有办法传入接口泛型对象。

比如： public ApiOut String (ApiIn)

他无法解析ApiIn,

但可以解析ApiOut

上面两个我都试过了

最后，我选择了smart-doc，废话不多说，直接上代码

1 POM文件，添加插件

<plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.2.1</version>
                <configuration>
                    <!--指定生成文档使用的配置文件-->
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                </configuration>
                <executions>
                    <execution>
                        <!--不需要在编译项目时自动生成文档可注释phase-->
                        <phase>compile</phase>
                        <goals>
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

最好别使用以下方式，我生成出来空文档。

<!-- https://mvnrepository.com/artifact/com.github.shalousun/smart-doc -->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc</artifactId>
    <version>2.2.1</version>
</dependency>

2 在项目的resources下，创建smart-doc.json

{
  "serverUrl": "http://127.0.0.1",
  "isStrict": false,
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,        //生成测试页面
  "projectName": "smart-doc"
}

3 测试接口泛型参数

 入参泛型

package com.tenyears.model.common;


/**
 * @author helka067
 * 调接口时，数据请求格式
 */
@Data
public class ApiRequest<T> {
    /**
     * 模型
     */
    private T data;
    /**
     * 当前页
     */
    private Integer pageIndex = 1;
    /**
     * 条目
     */
    private Integer pageSize= 10;

}

出参泛型

package com.tenyears.model.common;

/**
 * Created by Tyler on 2017/6/20.
 */
@Data
public class ApiResult<T> {

	/**
	 * 代码
	 */
	private String code = 0;
	/**
	 * 信息
	 */
	private String message = "Ok";
	/**
	 * 模型
	 */
	private T data;	


	
}

模型

package com.tenyears.webTest.model;

import com.tenyears.model.base.SuperBaseModel;
import lombok.Data;
import org.hibernate.annotations.GenericGenerator;

import javax.persistence.*;

/**
 * 标签
 */
@Data
public class AdTag {

  /**
   * 主键
   */
  private long tagID;

  /**
   * 父节点
   */
  private long tagParentID;

  /**
   * 标签名
   */
  private String tagName;


}

4，测试接口

package com.tenyears.webTest.controller;

import com.tenyears.model.common.ApiRequest;
import com.tenyears.model.common.ApiResult;
import com.tenyears.web.baseClass.BaseClass;
import com.tenyears.webTest.model.AdTag;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;

/**
 * @description :
 * @auther Tyler
 * @date 2021/6/5
 */

/**
 * 测试
 */
@RestController
@RequestMapping("api/test")
public class TestController extends BaseClass {

    @Value("${isDebug}")
    public String isDebug;

    /**
     * 测试接口
     * @return String
     * @throws Exception
     */
    @RequestMapping(value = "test1", method = RequestMethod.POST)
    public String test1() throws Exception {
        return "isDebug:"+isDebug;
    }

    /**
     * 广告标签
     * @param tag
     * @return
     * @throws Exception
     */
    @RequestMapping(value = "test2", method = RequestMethod.POST)
    public ApiResult<AdTag> test2(@RequestBody ApiRequest<AdTag> tag) throws Exception {
        return new ApiResult<>();
    }
}

5 生成文档

我选择了html，你们随意。

6 效果

 随笔：

1 Request-example

对于自动生成的请求示例，有些默认值不是我们要的。

可以通过@mock 标签解决

/**
     * 值
     * @mock [0,1,2,3,4,5,6]
     */
    private String val;