GoFrame WEB服務(wù)開發(fā)-接口文檔

?GoFrame?框架支持全自動化的接口文檔生成，保障代碼與接口文檔同步維護，自動生成的接口文檔采用的是標準的?OpenAPIv3?協(xié)議。在介紹?OpenAPIv3?協(xié)議之前，建議您先閱讀了解框架的規(guī)范路由特性：路由注冊-規(guī)范路由 。

一、OpenAPIv3

詳細的?OpenAPIv3?協(xié)議介紹請參考：https://swagger.io/specification/

二、g.Meta元數(shù)據(jù)

接口的元數(shù)據(jù)信息可以通過為輸入結(jié)構(gòu)體 ?embedded ?方式嵌入 ?g.Meta? 結(jié)構(gòu)，并通過 ?g.Meta? 的屬性標簽方式來實現(xiàn)。

三、常用協(xié)議標簽

輸入輸出結(jié)構(gòu)體中的屬性的標簽完整支持?OpenAPIv3?協(xié)議，因此只要增加了對應的協(xié)議標簽，那么生成的?OpenAPIv3?接口信息中將會自動包含該屬性。

大部分的標簽屬性已經(jīng)被?Server?組件自動生成，開發(fā)者需要手動設(shè)置的標簽不多。常見的標簽包括：

四、擴展OpenAPIv3信息

核心的接口信息已經(jīng)自動生成，如果開發(fā)者想要更進一步完善接口信息，可以通過?s.GetOpenApi()?接口獲取到?OpenAPIv3?的結(jié)構(gòu)體對象，并手動填充對應的屬性內(nèi)容即可。我們來看一個示例，在該示例中，我們將接口中的標簽進行了自定義的排序，并且增加了對每個標簽的詳細描述：

我們可以發(fā)現(xiàn)通過通用的?OpenAPIv3?對象我們可以自定義修改其內(nèi)容，并且根據(jù)它生成其他各種自定義類型的接口文檔。

五、常見問題

1、如何實現(xiàn)文件上傳的接口定義？

• 參數(shù)接收的數(shù)據(jù)類型使用?*ghttp.UploadFile ?
• 如果需要接口文檔也支持文件類型，那么參數(shù)的標簽中設(shè)置?type?為?file?類型