smart-doc功能使用介紹

時間 2019-11-12

標籤 smart doc 功能使用介紹简体版

原文原文鏈接

smart-doc從2018年8月份底開源發佈以來已經迭代了好幾個版本。在這裏很是感謝那些勇於用smart-doc去作嘗試並積極提出建議的社區用戶。所以決定在本博客中重要說明下smart-doc的功能，包括使用介紹。以減小後期用戶使用中的一些疑惑。html

1、簡介

Smart-doc是一個徹底無侵入的java Rest Api文檔生成工具。讓用戶的代碼保持整潔一直是Smart-doc的核心理念。java

2、特殊功能介紹

2.1 JSR303支持

在當前許多的web項目中，咱們都會直接使用JSR303來驗證參數的合法性包括檢驗參數是否爲必須參數等，smart-doc自己是爲了幫助開發人員少去寫一些無用的東西，整合標準的開發規範去幫助快速的生成文檔。所以smart-doc自誕生那一刻起就已經支持JRS303驗證規範。只要你寫在字段上加了JSR303的驗證註解或者是hibernate-validate的註解。smart-doc在輸出請求參數文檔時自動填寫參數必填爲true。請看代碼片斷：linux

public class Leader {
    /**
    * 姓名
    */
    @NotEmpty
    @Length(max = 5)
    private String name;
    /**
    * 生日
    */
    @NotBlank(message = "生日不能爲空")
    @Pattern(regexp = "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", message = "出生日期格式不正確")
    private String birthday;
    /**
    * 年齡
    */
    @Min(value = 0)
    private Integer age;
    /**
    * 科目
    */
    @Valid
    @NotNull(message = "")
    private Subject subject;
}

參數請求文檔：git

Parameter	Type	Description	Required
name	string	姓名	true
birthday	string	生日	true
age	int	年齡	false
subject	object	科目	true
└─subjectName	string	科目名稱	true

2.2 響應字段忽略

smart-doc可以自動解析fastjson和jackson的忽略字段註解正確輸出到文檔中。這個比較簡單就不詳細介紹了。github

2.3 json數據響應字段別名識別

smart-doc可以解析fastjson的JSONField註解的name屬性值和spring boot原始的jackson的JsonProperty註解value屬性值來自動完成別名輸出。作過json字段忽略都知道，這裏簡單介紹。web

public class SubUser {

    /**
     * 用戶名稱
     */
    private String subUserName;

    /**
     *
     */
    private BigInteger numbers;

    /**
     * 身份證
     */
    @JSONField(name = "id_card")
    private String idCard;
}

Response-fields:spring

Field	Type	Description
subUserName	string	用戶名稱
numbers	number	No comments found.
id_card	string	身份證

Response-example:數據庫

{
	"subUserName":"黎昕.鄭",
	"numbers":gzc1l6,
	"id_card":"370809198201092228"
}

2.4 請求參數忽略

開發中有時候咱們可能有時候會直接使用數據庫的對象模型去直接接收參數，可是像createTime、updateTime這樣的字段咱們是不但願輸出到請求參數接口文檔中。對於返回數據來講，其實比較好處理，smart-doc自己可以識別fastjson和jackson的字段忽略註解來過濾掉。對請求參數來講針對這種都沒有好的解決，不少文檔工具是經過添加註解，smart-doc通過使用頻率和遵循不引入註解的原則，添加一個註釋tag來提供請求參數過濾，這個註釋tag定義爲ignore。注意：該功能在1.5版本纔會有。apache

public class SubUser {

    /**
     * 用戶名稱
     */
    private String subUserName;

    /**
     * 身份證
     */
    private String idCard;

    /**
     * 性別
     * @required
     */
    private int gender;

    /**
     *  建立時間
     *  @ignore
     */
    private Timestamp createTime;

}

在Controller層用SubUser做爲參數接收，smart-doc輸出的參數請求文檔：json

Parameter	Type	Description	Required
subUserName	string	用戶名稱	false
numbers	number	No comments found.	false
idCard	string	身份證	false
gender	int	性別	true

2.5 參數自動模擬值生成

smart-doc爲了儘可能減小開發人員和測試人員造參數值的時間，針對常見的字段類型和經常使用字段命名規則提供自動造參數值的功能。下面直接看用例:

public class SubUser {

    /**
     * 姓名
     */
    private String name;

    /**
     * 年齡
     */
    private int age;

    /**
     * 身份證
     */
    @JSONField(name = "id_card")
    private String idCard;

    /**
     * 性別(0,1)
     *
     */
    private int gender;

    /**
     * 電子郵件
     */
    private String email;

    /**
     * 手機號
     */
    private String phone;

    /**
     *  建立時間
     *  @ignore
     */
    private Timestamp createTime;
}

下面是smart-doc自定生成文檔中響應數據，這個數據所有依賴源碼來推導完成。

Response-fields:

Field	Type	Description
name	string	姓名
age	int	年齡
id_card	string	身份證
gender	int	性別(0,1)
email	string	電子郵件
phone	string	手機號
createTime	object	建立時間

Response-example:

{
	"name":"明軒.石",
	"age":59,
	"id_card":"350308197203301780",
	"gender":0,
	"email":"聰健.邱@gmail.com",
	"phone":"17664304058",
	"createTime":"2018-10-23 00:20:19"
}

2.6 添加文檔變動記錄

在1.7版本開始，smart-doc添加了文檔變動記錄的記錄功能，生成的文檔更加符合實際的文檔交互場景。該功能須要在選擇使用allInOne設置的時候才生效。使用方式以下：

ApiConfig config = new ApiConfig();
config.setServerUrl("http://localhost:8080");
config.setAllInOne(true);
config.setOutPath("d:\\md2");
//不指定SourcePaths默認加載代碼爲項目src/main/java下的
config.setSourceCodePaths(
    SourceCodePath.path().setDesc("本項目代碼").setPath("src/main/java")
);
 //非必須項，只有當setAllInOne設置爲true時文檔變動記錄才生效，
 //https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
config.setRevisionLogs(
 RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("測試").setStatus("建立").setVersion("V1.0"),
 RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("測試2").setStatus("修改").setVersion("V2.0")
);

變動記錄在文檔頭部，markdown樣式以下

版本	時間	狀態	做者	備註
V1.0	2018/12/15	建立	chen	測試
V2.0	2018/12/16	修改	chen2	測試2

2.7 記錄字段變動版本

smart-doc的用戶在使用中提出了新增記錄字段變動版本的需求。這樣可以方便知道某一接口的接收參數字段或者是響應字段是何時新增的。秉承着簡潔的原則，smart-doc在實現這一功能是並未引入額外的註釋tag，而是直接利用了JAVA原生的@since這個tag來標記字段新增的版本。用例以下：

public class SubUser {

    /**
     * @since 1.0
     * 用戶名稱
     */
    private String subUserName;

    /**
     * 身份證
     */
    private String idCard;

    /**
     * 性別
     * @required
     */
    private int gender;

    /**
     *  建立時間
     *  @ignore
     */
    private Timestamp createTime;

}

Response-fields:

Field	Type	Description	Required	Since
subUserName	string	用戶名稱	false	1.0
numbers	number	No comments found.	false	-
idCard	string	身份證	false	-
gender	int	性別	true	-

3、如何讓smart-doc加載源碼

Smart-doc做爲一款徹底依賴源碼註釋來分析生成文檔的工具。若是沒有源代碼，那麼在生成文檔時將只能看到字段名和字段類型等信息，註釋相關的信息都將沒法生成，對於一個全部代碼都在一個單獨項目中的狀況，你不須要考慮人和東西，Smart-doc能完美的完成你想要的文檔，可是對一個多模塊項目，或者項目依賴了一個獨立的jar包的狀況，smart-doc將沒法加載到它所運行模塊以外的代碼。下面將會介紹如何來讓Smart-doc加載到運行模塊外的項目代碼：

3.1 經過`ApiConfig`類設置

代碼示例以下：

ApiConfig config = new ApiConfig();
//之前的版本爲setSourcePaths，SourceCodePath爲SourcePath
config.setSourceCodePaths(
        SourceCodePath.path().setDesc("本項目代碼").setPath("src/main/java"),
        //smart-doc對路徑自動會作處理，不管是window合適linux系統路徑，直接拷貝貼入便可
        SourceCodePath.path().setDesc("加載外部項目源碼").setPath("E:\\Test\\Mybatis-PageHelper-master\\src\\main\\java")
);

這樣smart-doc就能將外部的源碼載入。

3.2 經過maven的classifier來指定源碼包

這裏先看如何使用classifier來加載源碼包。

<!--依賴的庫-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>common-util</artifactId>
    <version>1.8.7</version>
</dependency>
<!--依賴庫源碼-->
<dependency>
    <groupId>com.github.shalousun</groupId>
    <artifactId>common-util</artifactId>
    <version>1.8.7</version>
    <classifier>sources</classifier>
    <!--設置爲test,項目發佈時source不會放入最終的產品包-->
    <scope>test</scope>
</dependency>

這樣不須要像上面同樣設置源碼加載路徑了。可是並非全部的打包都能有源碼包。須要在打包是作規範化處理。

公有jar包打規範

當你發佈公共jar包或者dubbo應用api接口共有jar包時，在maven的plugs中加入maven-source-plugin,示例以下：

<!-- Source -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

這樣發佈的時候就會生成一個[your jar name]-sources.jar的源碼包，這個包也會一塊兒發佈到私有倉庫。這樣就能夠經過classifier來指定sources了。若是仍是不清楚能夠直接參考smart-doc源碼的pom.xml配置。

注意： 經測試若是隻是經過install到本地，即使是指定了sources也沒法讀取到源碼，只有將公用的模塊deploy到nexus這樣的私服上才能正常使用。

4、在Spring Boot項目中生成和展現html文檔

smart-doc支持直接生成html靜態文檔，推薦生成的文檔放到項目src/main/resources/static/doc的目錄下，部署好服務後直接訪問http://localhost:8080/doc/api.html便可看到一個相似gitbook帶完美書籤的html文檔，文檔風格簡潔明瞭。操做步驟以下：

4.1 生成html文檔

編寫生成文檔的單元測試；代碼以下：

/**
     * 包括設置請求頭，缺失註釋的字段批量在文檔生成期使用定義好的註釋
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://localhost:8080");
        //設置用md5加密html文件名,不設置爲true，html的文件名將直接爲controller的名稱
        config.setMd5EncryptedHtmlName(true);
        config.setStrict(true);//true會嚴格要求註釋，推薦設置true
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);//輸出到static/doc下
        //不指定SourcePaths默認加載代碼爲項目src/main/java下的,若是項目的某一些實體來自外部代碼能夠一塊兒加載
        config.setSourceCodePaths(
                SourceCodePath.path().setDesc("本項目代碼").setPath("src/main/java")
        );
        long start = System.currentTimeMillis();
        HtmlApiDocBuilder.builderControllersApi(config);//此處使用HtmlApiDocBuilder，ApiDocBuilder提供markdown能力
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }

4.2 修改服務配置

若是Spring Boot服務配置了spring.resources.add-mappings=false，那麼服務器將不會處理靜態資源， smart-doc生成的html靜態api文檔也就不能訪問，此時只須要將配置改成true便可。固然這種配置最好放入配置中心，真正的生產服務器若是不但願暴露接口文檔能夠直接設置爲false關閉文檔。

4.3 html靜態api展現效果

5、smart-doc自定義註釋tag

tag名稱	描述
@ignore	ignore tag用於過濾請求參數對象上的某個字段，設置後smart-doc不輸出改字段到請求參數列表中。
@required	若是你沒有使用JSR303參數驗證規範實現的方式來標準字段，就可使用@required去標註請求參數對象的字段，標註smart-doc在輸出參數列表時會設置爲true。