使用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 效果