smart-doc 生成接口文檔

 

使用smart-doc 生成接口文檔

  方式一  插件方式    springboot 啟動類 運行生成接口文檔

1.pom文件 導入插件

 <!--smart-doc 生成接口文檔-->
            <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>
                    <!--指定項目名稱-->
                    <projectName>測試</projectName>
                    <!--smart-doc實現自動分析依賴樹加載第三方依賴的源碼，如果一些框架依賴庫加載不到導致報錯，這時請使用excludes排除掉-->
                    <excludes>
                        <!--格式為：groupId:artifactId;參考如下-->
                        <exclude>com.alibaba:fastjson</exclude>
                    </excludes>
                </configuration>
                <executions>
                    <execution>
                        <!--如果不需要在執行編譯時啟動smart-doc，則將phase注釋掉-->
                        <phase>compile</phase>
                        <goals>
                            <goal>html</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

2.resource目錄下  smart-doc.json 配置文件

{
  "serverUrl": "http://127.0.0.1",//服務器地址
  "isStrict": false,//是否用嚴格模式，嚴格模式強制檢查注釋
  "allInOne": true,//所有接口文檔合並生成到一個文檔
  "outPath": "src/main/resources/static/doc",//文檔的輸出路徑
  "projectName": "smart-doc"//指定項目名稱，用於顯示在文檔中
}

 

 

 

 方式二  jar包方式

1.pom 導入jar包

        <!--smart-doc 生成接口文檔-->
        <dependency>
            <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc</artifactId>
            <version>2.2.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

 

2.junit Test 運行 運行生成接口文檔

@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = IcbcServerAppApplication.class )
public class ApiTest {

    /**
     * 包括設置請求頭，缺失注釋的字段批量在文檔生成期使用定義好的注釋
     */
    @Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        config.setServerUrl("192.168.2.77:8082/");
        //true會將文檔合並導出到一個markdown
        config.setAllInOne(true);
        //生成html時加密文檔名不暴露controller的名稱
        config.setMd5EncryptedHtmlName(true);


        //指定文檔輸出路徑
        //@since 1.7 版本開始，選擇生成靜態html doc文檔可使用該路徑：DocGlobalConstants.HTML_DOC_OUT_PATH;
      //config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
        // @since 1.2,如果不配置該選項，則默認匹配全部的controller,
        // 如果需要配置有多個controller可以使用逗號隔開
        config.setPackageFilters("com.jdd.icbc.client.rest.IcbcUserAccountAutoRechargeConrtroller");
        //不指定SourcePaths默認加載代碼為項目src/main/java下的,如果項目的某一些實體來自外部代碼可以一起加載
//        config.setSourceCodePaths(
//                //自1.7.0版本開始，在此處可以不設置本地代碼路徑，單獨添加外部代碼路徑即可
//            SourceCodePath.path().setDesc("本項目代碼").setPath("src/main/java"),
//                SourceCodePath.path().setDesc("加載項目外代碼").setPath("E:\\ApplicationPower\\ApplicationPower\\Common-util\\src\\main\\java")
//        );
        //since 1.7.5
        //如果該選項的值為false,則smart-doc生成allInOne.md文件的名稱會自動添加版本號
        config.setCoverOld(true);
        //since 1.7.5
        //設置項目名(非必須)，如果不設置會導致在使用一些自動添加標題序號的工具顯示的序號不正常
        config.setProjectName("icbc-server-app");


//
        //非必須只有當setAllInOne設置為true時文檔變更記錄才生效，https://gitee.com/sunyurepository/ApplicationPower/issues/IPS4O
        config.setRevisionLogs(
                RevisionLog.builder().setRevisionTime("2021/08/06").setAuthor("zhangweifeng").setRemarks("自動充值接口文檔測試").setStatus("創建").setVersion("V1.0")
//                RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("測試2").setStatus("修改").setVersion("V2.0")
        );

        ApiDocBuilder.buildApiDoc(config);

        //@since 1.7+版本開始，smart-doc支持生成帶書簽的html文檔，html文檔可選擇下面額方式
        //HtmlApiDocBuilder.builderControllersApi(config);
        //@since 1.7+版本開始，smart-doc支撐生成AsciiDoc文檔，你可以把AsciiDoc轉成HTML5的格式。
        //@see https://gitee.com/sunyurepository/api-doc-test
        //AdocDocBuilder.builderControllersApi(config);

        System.out.println("生成接口文檔完成");
    }
}