怎么實現(xiàn)Java開發(fā)SpringBoot集成接口文檔

本篇內容介紹了“怎么實現(xiàn)Java開發(fā)SpringBoot集成接口文檔”的有關知識，在實際案例的操作過程中，不少人都會遇到這樣的困境，接下來就讓小編帶領大家學習一下如何處理這些情況吧！希望大家仔細閱讀，能夠學有所成！

swagger vs smart-doc

首先我們先看一下Swagger組件目前存在的主要問題：

Swagger的代碼侵入性比較強

這個很容易理解，要讓Swagger生成接口文檔必須要給方法或字段添加對應的注解，是存在代碼侵入的。

原生swagger不支持接口的參數(shù)分組

對于有做參數(shù)分組的接口，原生的Swagger并未支持，雖然我們通過擴展其組件可以讓其支持參數(shù)分組，但是畢竟要開發(fā)，而且還未支持最新的Swagger3版本。

那作為對比，smart-doc 是基于接口源碼分析來生成接口文檔，完全做到零注解侵入，你只需要按照java標準注釋的寫，smart-doc就能幫你生成一個簡易明了的markdown 或是一個像GitBook樣式的靜態(tài)html文檔。官方地址：https://gitee.com/smart-doc-team/smart-doc

簡單羅列一下smart-doc的優(yōu)點

零注解、零學習成本、只需要寫標準java注釋即可生成文檔。

基于源代碼接口定義自動推導，強大的返回結構推導。

支持Spring MVC,Spring Boot,Spring Boot Web Flux(controller書寫方式)。

支持Callable,Future,CompletableFuture等異步接口返回的推導。

支持JavaBean上的JSR303參數(shù)校驗規(guī)范，支持參數(shù)分組。

對一些常用字段定義能夠生成有效的模擬值。…

接下來我們來看看SpringBoot中如何集成smart-doc。

SpringBoot集成 smart-doc

smart-doc支持多種方式生成接口文檔：maven插件、gradle插件、單元測試（不推薦），這里我才用的是基于maven插件生成，步驟如下：

引入依賴，版本選擇最新版本

<!--引入smart-doc-->
<plugin>
  <groupId>com.github.shalousun</groupId>
  <artifactId>smart-doc-maven-plugin</artifactId>
  <version>2.2.7</version>
  <configuration>
    <configFile>./src/main/resources/smart-doc.json</configFile>
    <projectName>Smart-Doc初體驗</projectName>
  </configuration>
</plugin>

重點在 configFile中指定smart-doc配置文件 smart-doc.json

新建配置文件smart-doc.json

{
  "outPath": "src/main/resources/static/doc"
}

指定smart-doc生成的文檔路徑，其他配置項可以參考官方wiki。

通過執(zhí)行maven 命令生成對應的接口文檔

//生成html
mvn -Dfile.encoding=UTF-8 smart-doc:html

當然也可以通過idea中的maven插件生成

訪問接口文檔

生成接口文檔后我們通過 http://localhost:8080/doc/api.html 查看，效果如下：

看到這里的同學可能會呵呵一笑，就這？啥也沒有呀！這還想讓我替換Swagger？

別急，剛剛只是體驗了smart-doc的基礎功能，接下來我們通過豐富smart-doc的配置文件內容來增強其功能。

功能增強

1. 開啟調試

一個優(yōu)秀的接口文檔工具調試功能必不能少，smart-doc支持在線調試功能，只需要加入如下幾個配置項：

{
  "serverUrl": "http://localhost:8080",      -- 服務器地址
  "allInOne": true,                -- 是否將文檔合并到一個文件中，一般推薦為true
  "outPath": "src/main/resources/static/doc",  -- 指定文檔的輸出路徑
  "createDebugPage": true,           -- 開啟測試
  "allInOneDocFileName":"index.html",      -- 自定義文檔名稱
  "projectName": "初識smart-doc"        -- 項目名稱
}

通過"createDebugPage": true 開啟debug功能，在讓生成smart-doc生成文檔時直接放入到 static/doc/下，這樣可以直接啟動程序訪問頁面 http://localhost:8080/doc/index.html 進行開發(fā)調試。

有的開發(fā)人員直接在idea中使用【Open In Browser】打開smart-doc生成的debug頁面，如果非要這做，前端js請求后臺接口時就出現(xiàn)了跨域。因此你需要在后端配置跨域。

這里以 SpringBoot2.3.x 為例配置后端跨域：

@Configuration
public class WebMvcAutoConfig implements WebMvcConfigurer {

    @Bean
    public CorsFilter corsFilter() {
        final UrlBasedCorsConfigurationSource urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        final CorsConfiguration corsConfiguration = new CorsConfiguration();
        /* 是否允許請求帶有驗證信息 */
        corsConfiguration.setAllowCredentials(true);
        /* 允許訪問的客戶端域名 */
        corsConfiguration.addAllowedOrigin("*");
        /* 允許服務端訪問的客戶端請求頭 */
        corsConfiguration.addAllowedHeader("*");
        /* 允許訪問的方法名,GET POST等 */
        corsConfiguration.addAllowedMethod("*");
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);
        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

開啟跨域后我們就可以直接在靜態(tài)接口頁面中進行調試了。

2. 通用響應體

在 “SpringBoot 如何統(tǒng)一后端返回格式？老鳥們都是這樣玩的！”一文中我們通過實現(xiàn) ResponseBodyAdvice對所有返回值進行了包裝，給前端返回統(tǒng)一的數(shù)據(jù)結構ResultData，我們需要讓其在接口文檔中也有此功能，在配置文件追加配置內容：

{
  "responseBodyAdvice":{            -- 通用響應體
    "className":"com.jianzh6.blog.base.ResultData"
  }
}

3. 自定義Header

在前后端分離項目中我們一般需要在請求接口時設置一個請求頭，如token，Authorization等…后端根據(jù)請求頭判斷是否為系統(tǒng)合法用戶，目前smart-doc也對其提供了支持。

在smart-doc配置文件 smart-doc.json中繼續(xù)追加如下配置內容：

"requestHeaders": [ //設置請求頭，沒有需求可以不設置
    {
      "name": "token",//請求頭名稱
      "type": "string",//請求頭類型
      "desc": "自定義請求頭 - token",//請求頭描述信息
      "value":"123456",//不設置默認null
      "required": false,//是否必須
      "since": "-",//什么版本添加的改請求頭
      "pathPatterns": "/smart/say",//只有以/smart/say 開頭的url才會有此請求頭
      "excludePathPatterns":"/smart/add,/smart/edit" // url=/app/page/將不會有該請求頭
    }
]

效果如下：

4. 參數(shù)分組

演示一下smart-doc對于參數(shù)分組的支持

新增操作時，age、level為必填項，sex為非必填。

編輯操作時，id，appid，leven為必填項，sex為非必填。

通過上面的效果可以看出smart-doc對于參數(shù)分組是完全支持的。

5. idea配置doc

自定義的tag默認是不會自動提示的，需要用戶在idea中進行設置。設置好后即可使用，下面以設置smart-doc自定義的mock tag為例，設置操作如下：

6. 完整配置

附上完整配置，如果還需要其他配置大家可以參考wiki自行引入。

{
  "serverUrl": "http://localhost:8080",
  "allInOne": true,
  "outPath": "src/main/resources/static/doc",
  "createDebugPage": true,
  "allInOneDocFileName":"index.html",
  "projectName": "初識smart-doc",
  "packageFilters": "com.jianzh6.blog.smartdoc.*",
  "errorCodeDictionaries": [{
    "title": "title",
    "enumClassName": "com.jianzh6.blog.base.ReturnCode",
    "codeField": "code",
    "descField": "message"
  }],
  "responseBodyAdvice":{
    "className":"com.jianzh6.blog.base.ResultData"
  },
  "requestHeaders": [{
    "name": "token",
    "type": "string",
    "desc": "自定義請求頭 - token",
    "value":"123456",
    "required": false,
    "since": "-",
    "pathPatterns": "/smart/say",
    "excludePathPatterns":"/smart/add,/smart/edit"
  }]
}

“怎么實現(xiàn)Java開發(fā)SpringBoot集成接口文檔”的內容就介紹到這里了，感謝大家的閱讀。如果想了解更多行業(yè)相關的知識可以關注億速云網(wǎng)站，小編將為大家輸出更多高質量的實用文章！