開源API文檔工具- swagger2 與 smart-doc 比較 與 使用

工具開源地址

swagger2 : https://swagger.io/

smart-doc： https://www.oschina.net/p/smart-doc  國產

兩者的比較

swagger2 和 smart-doc 兩個開源工具 都可以 使用jar包 生成 api 文檔。

相同點：

這個兩個工具 都可以 自動 掃描 有 @Controller 注解的 類 並生成  相應的 api 接口文檔。都可以生成 靜態網頁，提供在線api html 頁面的訪問。

 

區別：

1、swagger2相對 功能多一點，它不僅能 生成 文檔 ，而且還可以 提供在線測試 api 的頁面，方便調試。尤其是post 請求調試，不需要自己寫 json 格式請求數據了，只要在對應的請求屬性輸入對應的值就可以測試了，這個功能比較方便。而 smart-doc 只能生成 文檔，格式包含（多種格式文檔：Markdown、HTML5、Asciidoctor、Postman json）

2、設計思路不同，smart-doc 是基於 源碼分析的，它生成api文檔是通過分析JAVA源碼主要是通過 注釋 和 系統自帶注解，來實現文檔的 生成，而 swagger 是運行時 自動生成在線文檔，並且 生成 測試 接口的 案例。由於他們設計思路 理念 不一樣，swagger2 使用過程需要使用它定義的@API 相關注解，這樣就污染了源碼，代碼入侵有點高，而smart -doc 就不一樣了，主要是通過 注釋 、解析/** */ 來生成API文檔的 。這樣基本上沒有入侵性，很自由！

3、swagger 生成 離線的文檔 需要借助第三方jar包實現，而 smart-doc 直接 運行 test 方法就可以直接導出 md，html，asciidoc 等格式文檔。

兩個工具的使用

（基於 spring-boot的 使用Demo） 使用maven 構建項目和管理依賴的 

swagger2: 

1、引入依賴包

<springfox-swagger2.version>2.9.2</springfox-swagger2.version>

        <!-- swagager api 依賴包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-swagger2.version}</version>
        </dependency>

 

2、編寫swagger 配置類

@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "org.demo.SpringCloud.web";
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//api接口包掃描路徑
                .paths(PathSelectors.any())//可以根據url路徑設置哪些請求加入文檔，忽略哪些請求

                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2 接口文檔示例")//設置文檔的標題
                .description("更多內容請關注：http://www.baidu.com")//設置文檔的描述->1.Overview
                .version(VERSION)//設置文檔的版本信息-> 1.1 Version information
                .contact(new Contact("SpringCloud", "http://www.baidu.com", "[e-mail]"))//設置文檔的聯系方式->1.2 Contact information
                .termsOfServiceUrl("https://baidu.com")//設置文檔的License信息->1.3 License information
                .build();
    }

    /**
     * 防止@EnableMvc把默認的靜態資源路徑覆蓋了，手動設置的方式
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解決靜態資源無法訪問
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解決swagger無法訪問
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解決swagger的js文件無法訪問
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

　　

3、啟動項目 訪問 swagger-ui

 

 

 

 

smart-doc

1、引入依賴包

<smart-doc.version>1.8.6</smart-doc.version>

        <!-- smart-doc 依賴包 -->
        <dependency>
            <groupId>com.github.shalousun</groupId>
            <artifactId>smart-doc</artifactId>
            <version>${smart-doc.version}</version>
            <scope>test</scope>
        </dependency>

 

2、使用 @Test 方法 生成 api 文檔 

@Test
    public void testBuilderControllersApi() {
        ApiConfig config = new ApiConfig();
        //當把AllInOne設置為true時，Smart-doc將會把所有接口生成到一個Markdown、HHTML或者AsciiDoc中
        config.setAllInOne(true);
        config.setLanguage(DocLanguage.CHINESE);
        //Set the api document output path.
        config.setOutPath("d:/smart-doc/");
        //生成Markdown文件
        ApiDocBuilder.buildApiDoc(config);
    }
@Test
    public void testBuilderControllersApiHtml() {
        String OUTPUT_PATH = "smart-doc/html/";
        ApiConfig config = new ApiConfig();
        config.setServerUrl("http://127.0.0.1:8080");
        //設置為嚴格模式，Smart-doc將降至要求每個Controller暴露的接口寫上標准文檔注釋
//        config.setStrict(true);
        //當把AllInOne設置為true時，Smart-doc將會把所有接口生成到一個Markdown、HHTML或者AsciiDoc中
        config.setAllInOne(true);
        config.setLanguage(DocLanguage.CHINESE);
        //HTML5文檔，建議直接放到src/main/resources/static/doc下，Smart-doc提供一個配置常量HTML_DOC_OUT_PATH
        config.setOutPath(DocGlobalConstants.HTML_DOC_OUT_PATH);
        config.setOutPath(OUTPUT_PATH);
        // 設置接口包掃描路徑過濾，如果不配置則Smart-doc默認掃描所有的接口類
        // 配置多個報名有英文逗號隔開
//        config.setPackageFilters("com.power.doc.controller");
        //設置公共請求頭.如果不需要請求頭，則無需設置
//        config.setRequestHeaders(
//                ApiReqHeader.header().setName("access_token").setType("string")
//                        .setDesc("Basic auth credentials").setRequired(true).setSince("v1.1.0"),
//                ApiReqHeader.header().setName("user_uuid").setType("string").setDesc("User Uuid key")
//        );

        //設置錯誤錯列表，遍歷自己的錯誤碼設置給Smart-doc即可
        List<ApiErrorCode> errorCodeList = new ArrayList<>();
        for (HttpCodeEnum codeEnum : HttpCodeEnum.values()) {
            ApiErrorCode errorCode = new ApiErrorCode();
            errorCode.setValue(codeEnum.getCode()).setDesc(codeEnum.getMessage());
            errorCodeList.add(errorCode);
        }
        //不需要顯示錯誤碼,則可以不用設置錯誤碼。
        config.setErrorCodes(errorCodeList);
        //1.7.9 優化了錯誤碼處理，用於下面替代遍歷枚舉設置錯誤碼
        //不需在文檔中展示錯誤碼則可以不設置。
//        config.setErrorCodeDictionaries(
//                ApiErrorCodeDictionary.dict().setEnumClass(HttpCodeEnum.class)
//                        .setCodeField("code") //錯誤碼值字段名
//                        .setDescField("desc")//錯誤碼描述
//        );


        //設置文檔變更記錄，沒有需要可以不設置
//        config.setRevisionLogs(
//                RevisionLog.getLog().setRevisionTime("2018/12/15").setAuthor("chen").setRemarks("test").setStatus("create").setVersion("V1.0"),
//                RevisionLog.getLog().setRevisionTime("2018/12/16").setAuthor("chen2").setRemarks("test2").setStatus("update").setVersion("V2.0")
//        );

        long start = System.currentTimeMillis();
        //since 1.8.1版本開始入口方法有變更
        HtmlApiDocBuilder.buildApiDoc(config);
        long end = System.currentTimeMillis();
        DateTimeUtil.printRunTime(end, start);
    }

　

 生成文檔文件

 

 

 

 

 

 

 

總結：

如果 你 只想 生成 api 文檔功能的 話  推薦使用 smart - doc ，更方便 無入侵！ 如果你不僅想生成文檔，還想使用 測試接口 功能，那就 用swagger 吧！

PS 一般 文檔不是要是 word格式嘛，那怎么辦尼？用java代碼生成word，那太麻煩了，而且不太好弄，這里有個小技巧，那就是 生成html格式 文檔，然后打開 html文件 全選，復制，新建一個word文檔，然后把剛剛拷貝的內容粘貼進去，這樣 word格式的 api 文檔就搞定了！格式基本上沒有什么問題，而且目錄文檔清晰，本人親測，只是在復制的過程中 可能表格格式會有點問題，不能正常全部顯示，解決辦法請移步 ：https://www.cnblogs.com/geekswg/#/cnblog/works/article/13041255