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

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

 

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

 

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

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

比如： public ApiOut<User> String (ApiIn<User>)

他无法解析ApiIn<User>,

但可以解析ApiOut<User>

 

上面两个我都试过了

最后，我选择了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>
                    <!--指定分析的依赖模块（避免分析所有依赖，导致生成文档变慢，循环依赖导致生成失败等问题）-->
                    <includes>
                        <!--格式为：groupId:artifactId;参考如下-->
                        <include>com.alibaba:fastjson</include>

                    </includes>
                </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 效果