c語言api介面文檔生成工具,如何生成api文檔

本文目錄一覽：

• 1、請問有沒有用於API(C語言)的畫界面,方便添加按鈕的工具?或方法?
• 2、還在發愁寫API文檔？推薦一款阿里騰訊都在用的API管理神器
• 3、YAPI:從0搭建API文檔管理工具
• 4、神器 SpringDoc 橫空出世！最適合 SpringBoot 的API文檔工具來了

請問有沒有用於API(C語言)的畫界面,方便添加按鈕的工具?或方法?

在 OFFICE VISO 2003中就有啊，你安裝一個。打開VISIO，新建一個文檔，在「軟體」/「WINDOWS界面」中就用各種類型的控制項和窗體的元素可以使用，就像設計UML圖一樣。

還在發愁寫API文檔？推薦一款阿里騰訊都在用的API管理神器

作為一個前後端分離模式開發的團隊，我們經常會看到這樣的場景：前端開發和後端開發在一起熱烈的討論「你這介面參數怎麼又變了？」，「介面怎麼又不通了？」，「稍等，我調試下」，「你再試試…”。

那能不能寫好介面文檔，大家都按文檔來開發？很難，因為寫文檔、維護文檔比較麻煩，而且費時，還會經常出現 API 更新了，但文檔還是舊的，各種同步不一致的情況，從而耽擱彼此的時間。

之前我們團隊也遇到了同樣的問題，那麼作為研發團隊的負責人，我是如何帶領團隊解決這個問題的呢？

方法其實很簡單，如果能做到讓寫文檔/維護文檔這件事情的短期收益就能遠高於付出的成本，那麼所有問題都能迎刃而解，開發人員就會非常樂意去寫介面文檔。

要做到寫文檔和及時維護文檔的短期收益就能遠高於付出的成本，無非兩個方向：

鑒於此，我們設想如果有一款工具做到以下這些是不是就非常爽了？

總結下來，我們需要的就是這麼一款工具：

為此，我們幾乎嘗遍了市面上所有相關的工具，但是很遺憾，沒有找到合適的。

於是，我們自己實現了一個Postman + Swagger + RAP + JMeter

這個工具就是 Apifox，經常很長一段時間不斷更新迭代後，我們基本上完全實現了最初的設想，幾乎完美解決了最開始遇到的所有問題，在公司內部大受歡迎。並且也形成了我們自己的最佳實踐。

沒錯，現在我們已經將Apifox產品化對外服務了，你們團隊也可以直接使用Apifox了。

官網：

Apifox = Postman + Swagger + Mock + JMeter

Apifox 是 API 文檔、API 調試、API Mock、API 自動化測試一體化協作平台。

通過一套系統、一份數據，解決多個系統之間的數據同步問題。只要定義好介面文檔，介面調試、數據 Mock、介面測試就可以直接使用，無需再次定義；介面文檔和介面開發調試使用同一個工具，介面調試完成後即可保證和介面文檔定義完全一致。高效、及時、準確！

節省研發團隊的每一分鐘！

如果你認為 Apifox 只做了數據打通，來提升研發團隊的效率，那就錯了。Apifox 還做了非常多的創新，來提升開發人員的效率。

通常一個介面會有多種情況用例，比如 正確用例 參數錯誤用例 數據為空用例 不同數據狀態用例。定義介面的時候定義好這些不同狀態的用例，介面調試的時候直接運行，非常高效。

可以獨立定義數據模型，介面定義時可以直接引用數據模型，數據模型之間也可以相互引用。同樣的數據結構，只需要定義一次即可多處使用；修改的時候只需要修改一處，多處實時更新，避免不一致。

使用 Apifox 調試介面的時候，系統會根據介面文檔里的定義，自動校驗返回的數據結構是否正確，無需通過肉眼識別，也無需手動寫斷言腳本檢測，非常高效！

Apifox 自動校驗數據結構

設置斷言：

Apifox 設置斷言

運行後，查看斷言結果：

先放一張圖對比下 Apifox 和其他同類工具 零配置 mock 出來的數據效果：

Apifox Mock 數據結果對比同類工具

可以看出 Apifox 零配置 Mock 出來的數據和真實情況是非常接近的，前端開發可以直接使用，而無需再手動寫 mock 規則。

「Apifox 如何做到高效率、零配置生成非常人性化的 mock 數據」

Apifox 項目可「在線分享」 API 文檔，分享出去的 API 文檔可設置為公開或需要密碼訪問，非常方便與外部團隊協作。

體驗地址：

根據介面模型定義，自動生成各種語言/框架（如 TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等）的業務代碼（如 Model、Controller、單元測試代碼等）和介面請求代碼。目前 Apifox 支持 130 種語言及框架的代碼自動生成。

更重要的是：你可以通過自定義代碼模板來生成符合自己團隊的架構規範的代碼，滿足各種個性化的需求。

介面調試

Apifox 多種主題色可選

YAPI:從0搭建API文檔管理工具

最近在找一款API文檔管理工具，之前有用過Swagger、API Manager、Confluence，現在用的還是Confluence。

我個人一直不喜歡用Swagger，感覺「代碼即文檔」，讓代碼里的文檔無處不在，已經對代碼造成了一定的入侵了。API Manager就是一個純API文檔管理的工具了。Confluence是萬能的，也是最簡單的，支持各種插件在線安裝，可以有各種布局，支持MD文檔，也支持表格、代碼塊等。

最近看到一篇文章在說YAPI，就準備搭建一個試試效果如何。

YAPI是去哪兒網開源的一款API管理工具，理念如下：

特性：

選擇YAPI試試手的原因是因為我看到了它支持MockServer，這樣前端開發同學就不用等待後端同學了。主要是我也懶得搭建一套mock服務，有這樣一款工具何樂而不為呢？所以今天就找了一台伺服器安裝了一下。考慮排版問題，就以圖片形式放出來了。

nodeJS長期支持版本官網下載地址：，下載後執行如下命令：

nodeJS安裝完畢。

YAPI安裝，GitHub上已經有比較詳細的文檔了，地址：，這裡說一下兩種部署方式：

可視化部署：

yapi安裝完畢，訪問進行可視化配置一步一步往下走即可。

命令行部署（推薦方式）：

yapi安裝完畢，訪問:{config.json中配置的port}即可訪問。

node需要安裝pm2模塊，使用pm2模塊後台運行yapi：

運行成功頁面：

至此，YAPI就安裝完畢了，簡單實用一下還是不錯的，因為是國產的，整體操作風格還是比較習慣的。在YAPI這裡介面更改還有記錄哦~

後面再慢慢體驗這個裡面的一些高級功能吧，比如MockServer、介面測試等功能。

大家還有什麼更好用的API管理工具？你覺得一款優秀的API管理工具應該都有哪些必須的功能？歡迎推薦和討論！

神器 SpringDoc 橫空出世！最適合 SpringBoot 的API文檔工具來了

之前在SpringBoot項目中一直使用的是SpringFox提供的Swagger庫，上了下官網發現已經有接近兩年沒出新版本了！前幾天升級了SpringBoot 2.6.x 版本，發現這個庫的兼容性也越來越不好了，有的常用註解屬性被廢棄了居然都沒提供替代！無意中發現了另一款Swagger庫SpringDoc，試用了一下非常不錯，推薦給大家！

SpringDoc簡介

SpringDoc是一款可以結合SpringBoot使用的API文檔生成工具，基於OpenAPI 3，目前在Github上已有1.7K+Star，更新發版還是挺勤快的，是一款更好用的Swagger庫！值得一提的是SpringDoc不僅支持Spring WebMvc項目，還可以支持Spring WebFlux項目，甚至Spring Rest和Spring Native項目，總之非常強大，下面是一張SpringDoc的架構圖。

使用

接下來我們介紹下SpringDoc的使用，使用的是之前集成SpringFox的mall-tiny-swagger項目，我將把它改造成使用SpringDoc。

集成

首先我們得集成SpringDoc，在pom.xml中添加它的依賴即可，開箱即用，無需任何配置。

!–springdoc 官方Starter–org.springdocspringdoc-openapi-ui1.6.6

從SpringFox遷移

我們先來看下經常使用的Swagger註解，看看SpringFox的和SpringDoc的有啥區別，畢竟對比已學過的技術能該快掌握新技術；

接下來我們對之前Controller中使用的註解進行改造，對照上表即可，之前在@Api註解中被廢棄了好久又沒有替代的description屬性終於被支持了！

/**

* 品牌管理Controller

* Created by macro on 2019/4/19.

*/@Tag(name =”PmsBrandController”, description =”商品品牌管理”)@Controller@RequestMapping(“/brand”)publicclassPmsBrandController{@AutowiredprivatePmsBrandService brandService;privatestaticfinalLogger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);@Operation(summary =”獲取所有品牌列表”,description =”需要登錄後訪問”)@RequestMapping(value =”listAll”, method = RequestMethod.GET)@ResponseBodypublicCommonResult getBrandList() {returnCommonResult.success(brandService.listAllBrand());    }@Operation(summary =”添加品牌”)@RequestMapping(value =”/create”, method = RequestMethod.POST)@ResponseBody@PreAuthorize(“hasRole(‘ADMIN’)”)publicCommonResult createBrand(@RequestBodyPmsBrand pmsBrand) {        CommonResult commonResult;        int count = brandService.createBrand(pmsBrand);if(count ==1) {            commonResult = CommonResult.success(pmsBrand);            LOGGER.debug(“createBrand success:{}”, pmsBrand);        }else{            commonResult = CommonResult.failed(“操作失敗”);            LOGGER.debug(“createBrand failed:{}”, pmsBrand);        }returncommonResult;    }@Operation(summary =”更新指定id品牌信息”)@RequestMapping(value =”/update/{id}”, method = RequestMethod.POST)@ResponseBody@PreAuthorize(“hasRole(‘ADMIN’)”)publicCommonResult updateBrand(@PathVariable(“id”)Longid,@RequestBodyPmsBrand pmsBrandDto, BindingResult result) {        CommonResult commonResult;        int count = brandService.updateBrand(id, pmsBrandDto);if(count ==1) {            commonResult = CommonResult.success(pmsBrandDto);            LOGGER.debug(“updateBrand success:{}”, pmsBrandDto);        }else{            commonResult = CommonResult.failed(“操作失敗”);            LOGGER.debug(“updateBrand failed:{}”, pmsBrandDto);        }returncommonResult;    }@Operation(summary =”刪除指定id的品牌”)@RequestMapping(value =”/delete/{id}”, method = RequestMethod.GET)@ResponseBody@PreAuthorize(“hasRole(‘ADMIN’)”)publicCommonResult deleteBrand(@PathVariable(“id”)Longid) {        int count = brandService.deleteBrand(id);if(count ==1) {            LOGGER.debug(“deleteBrand success :id={}”, id);returnCommonResult.success(null);        }else{            LOGGER.debug(“deleteBrand failed :id={}”, id);returnCommonResult.failed(“操作失敗”);        }    }@Operation(summary =”分頁查詢品牌列表”)@RequestMapping(value =”/list”, method = RequestMethod.GET)@ResponseBody@PreAuthorize(“hasRole(‘ADMIN’)”)publicCommonResult listBrand(@RequestParam(value =”pageNum”, defaultValue =”1″)@Parameter(description =”頁碼”)Integer pageNum,@RequestParam(value =”pageSize”, defaultValue =”3″)@Parameter(description =”每頁數量”)Integer pageSize) {        List brandList = brandService.listBrand(pageNum, pageSize);returnCommonResult.success(CommonPage.restPage(brandList));    }@Operation(summary =”獲取指定id的品牌詳情”)@RequestMapping(value =”/{id}”, method = RequestMethod.GET)@ResponseBody@PreAuthorize(“hasRole(‘ADMIN’)”)publicCommonResult brand(@PathVariable(“id”)Longid) {returnCommonResult.success(brandService.getBrand(id));    }}

接下來進行SpringDoc的配置，使用OpenAPI來配置基礎的文檔信息，通過GroupedOpenApi配置分組的API文檔，SpringDoc支持直接使用介面路徑進行配置。

/**

* SpringDoc API文檔相關配置

* Created by macro on 2022/3/4.

*/@ConfigurationpublicclassSpringDocConfig{@BeanpublicOpenAPImallTinyOpenAPI(){returnnewOpenAPI()                .info(newInfo().title(“Mall-Tiny API”)                        .description(“SpringDoc API 演示”)                        .version(“v1.0.0”)                        .license(newLicense().name(“Apache 2.0”).url(“”)))                .externalDocs(newExternalDocumentation()                        .description(“SpringBoot實戰電商項目mall（50K+Star）全套文檔”)                        .url(“”));    }@BeanpublicGroupedOpenApipublicApi(){returnGroupedOpenApi.builder()                .group(“brand”)                .pathsToMatch(“/brand/**”)                .build();    }@BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder()                .group(“admin”)                .pathsToMatch(“/admin/**”)                .build();    }}

結合SpringSecurity使用

由於我們的項目集成了SpringSecurity，需要通過JWT認證頭進行訪問，我們還需配置好SpringDoc的白名單路徑，主要是Swagger的資源路徑；

/**

* SpringSecurity的配置

* Created by macro on 2018/4/26.

*/@Configuration@EnableWebSecurity@EnableGlobalMethodSecurity(prePostEnabled = true)public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(HttpSecurity httpSecurity) throws Exception {httpSecurity.csrf()// 由於使用的是JWT，我們這裡不需要csrf.disable().sessionManagement()// 基於token，所以不需要session.sessionCreationPolicy(SessionCreationPolicy.STATELESS).and().authorizeRequests().antMatchers(HttpMethod.GET,// Swagger的資源路徑需要允許訪問”/”,”/swagger-ui.html”,”/swagger-ui/”,”/*.html”,”/favicon.ico”,”/**/*.html”,”/**/*.css”,”/**/*.js”,”/swagger-resources/**”,”/v3/api-docs/**”).permitAll().antMatchers(“/admin/login”)// 對登錄註冊要允許匿名訪問.permitAll().antMatchers(HttpMethod.OPTIONS)//跨域請求會先進行一次options請求.permitAll().anyRequest()// 除上面外的所有請求全部需要鑒權認證.authenticated();            }}

然後在OpenAPI對象中通過addSecurityItem方法和SecurityScheme對象，啟用基於JWT的認證功能。

/**

* SpringDoc API文檔相關配置

* Created by macro on 2022/3/4.

*/@ConfigurationpublicclassSpringDocConfig{privatestaticfinalString SECURITY_SCHEME_NAME =”BearerAuth”;@BeanpublicOpenAPImallTinyOpenAPI(){returnnewOpenAPI()                .info(newInfo().title(“Mall-Tiny API”)                        .description(“SpringDoc API 演示”)                        .version(“v1.0.0”)                        .license(newLicense().name(“Apache 2.0”).url(“”)))                .externalDocs(newExternalDocumentation()                        .description(“SpringBoot實戰電商項目mall（50K+Star）全套文檔”)                        .url(“”))                .addSecurityItem(newSecurityRequirement().addList(SECURITY_SCHEME_NAME))                .components(newComponents()                                .addSecuritySchemes(SECURITY_SCHEME_NAME,newSecurityScheme()                                                .name(SECURITY_SCHEME_NAME)                                                .type(SecurityScheme.Type.HTTP)                                                .scheme(“bearer”)                                                .bearerFormat(“JWT”)));    }}

測試

接下來啟動項目就可以訪問Swagger界面了，訪問地址：

我們先通過登錄介面進行登錄，可以發現這個版本的Swagger返回結果是支持高亮顯示的，版本明顯比SpringFox來的新；

然後通過認證按鈕輸入獲取到的認證頭信息，注意這裡不用加bearer前綴；

之後我們就可以愉快地訪問需要登錄認證的介面了；

看一眼請求參數的文檔說明，還是熟悉的Swagger樣式！

常用配置

SpringDoc還有一些常用的配置可以了解下，更多配置可以參考官方文檔。

springdoc:swagger-ui:# 修改Swagger UI路徑path:/swagger-ui.html# 開啟Swagger UI界面enabled:trueapi-docs:# 修改api-docs路徑path:/v3/api-docs# 開啟api-docsenabled:true# 配置需要生成介面文檔的掃描包packages-to-scan:com.macro.mall.tiny.controller# 配置需要生成介面文檔的介面路徑paths-to-match:/brand/**,/admin/**

總結

在SpringFox的Swagger庫好久不出新版的情況下，遷移到SpringDoc確實是一個更好的選擇。今天體驗了一把SpringDoc，確實很好用，和之前熟悉的用法差不多，學習成本極低。而且SpringDoc能支持WebFlux之類的項目，功能也更加強大，使用SpringFox有點卡手的朋友可以遷移到它試試！

參考資料

項目地址：

官方文檔：

項目源碼地址