将夜猫腻小说,大主宰之灵路天蚕土豆,欢乐颂

首先，Swagger 這個工具能夠自動生成 API 接口文檔，在線調試，節省了很多書寫文檔的時間，非常強大。

但是，想要文檔生成的合格，還是要書寫大量的注解。有沒有一種連注解都不用寫的方式呢？

smart-doc簡介

今天了不起給大家推薦一個技術：smart-doc，看名字就知道，它是智能-文檔。直接分析代碼，根據代碼含義生成文檔（開個玩笑，它還沒有那么智能）；其實它是利用的注釋，來生成文檔，還是需要寫注釋的。

官方介紹：smart-doc是一款同時支持JAVA REST API和Apache Dubbo RPC接口文檔生成的工具，smart-doc在業內率先提出基于JAVA泛型定義推導的理念，完全基于接口源碼來分析生成接口文檔，不采用任何注解侵入到業務代碼中。你只需要 按照java-doc標準編寫注釋 ， smart-doc就能幫你生成一個簡易明了的Markdown、HTML5、Postman Collection2.0+、OpenAPI 3.0+的文檔。

swagger和smart-doc的對比

我們來看看swagger和smart-doc的區別

來看看smart-doc 的代碼

如果是swagger 的寫法，每個字段都要加上 @ApiModelProperty("xxx") 的注解，如果有幾十個字段，幾十個類，那代碼量多的可不小。

不過這些類一般都是自動生成工具生成的，對寫代碼的人影響不大，不過這樣子寫倒是簡潔了不少，甚得我意~

可能有人就說了，我不寫注釋，只寫swagger注解，看起來也很簡潔，這也確實沒錯。

確實看起來很簡潔，不過沒有文檔注釋的情況下，在其他類里你是看不到這個字段的解釋的，每次找字段都得回到這個類看看到底是不是這個字段。如果你和同事們的英語都 very good，當我沒說。

如果是api接口，smart-doc想要生成文檔，需要寫成這樣（好像看起來什么都沒寫）

而swagger就需要加上@ApiOperation()這個注解，如果是個參數多的接口，還需要@ApiImplicitParams()這個注解，徒增學習成本

使用smart-doc

總共需要3步：

引入pom依賴，是一個插件


plugin>
    groupId>com.github.shalousungroupId>
    artifactId>smart-doc-maven-pluginartifactId>
    version>${smart-doc-plugin.version}version>
    configuration>
        
        configFile>${basedir}/src/main/resources/smart-doc.jsonconfigFile>
        
        projectName>${project.name}projectName>
        excludes>
            
            
            exclude>com.fu:common-.*exclude>
            exclude>com.fu:generatorexclude>
        excludes>
    configuration>
    executions>
        execution>
            
            phase>compilephase>
            goals>
                goal>openapigoal>
            goals>
        execution>
    executions>
plugin>

編寫smart-doc.json文件

{
  // 參考文檔：https://smart-doc-group.github.io/#/zh-cn/start/quickstart
  "outPath": "D:\\111",

  "coverOld": true,
  "allInOne": true, // 是否將文檔合并到一個文件中，一般推薦為true
  "createDebugPage": true,//@since 2.0.0 smart-doc支持創建可以測試的html頁面，僅在AllInOne模式中起作用。
  "isStrict": false, //是否開啟嚴格模式
  // controller包過濾，多個包用英文逗號隔開
  "packageFilters": "com.fu.system.controller.*",
  "projectName": "system",
  "sortByTitle": true, // 接口排序
  "ignoreRequestParams":[ //忽略請求參數對象，把不想生成文檔的參數對象屏蔽掉，@since 1.9.2
    "javax.servlet.http.HttpServletRequest",
    "javax.servlet.http.HttpServletResponse",
    "javax.servlet.http.HttpSession"
   ]
}