建站
咨詢
售后
建站咨詢
新聞中心
?GOFrame?框架支持全自動化的接口文檔生成，保障代碼與接口文檔同步維護(hù)，自動生成的接口文檔采用的是標(biāo)準(zhǔn)的?OpenAPIv3?協(xié)議。在介紹?OpenAPIv3?協(xié)議之前，建議您先閱讀了解框架的規(guī)范路由特性：路由注冊-規(guī)范路由 。
一、OpenAPIv3
詳細(xì)的?OpenAPIv3?協(xié)議介紹請參考：https://swagger.io/specification/
二、g.Meta元數(shù)據(jù)
接口的元數(shù)據(jù)信息可以通過為輸入結(jié)構(gòu)體 ?embedded ?方式嵌入 ?g.Meta? 結(jié)構(gòu)，并通過 ?g.Meta? 的屬性標(biāo)簽方式來實現(xiàn)。
三、常用協(xié)議標(biāo)簽
輸入輸出結(jié)構(gòu)體中的屬性的標(biāo)簽完整支持?OpenAPIv3?協(xié)議，因此只要增加了對應(yīng)的協(xié)議標(biāo)簽，那么生成的?OpenAPIv3?接口信息中將會自動包含該屬性。
大部分的標(biāo)簽屬性已經(jīng)被?Server?組件自動生成，開發(fā)者需要手動設(shè)置的標(biāo)簽不多。常見的標(biāo)簽包括：
| 常見OpenAPIv3標(biāo)簽 | 說明 | 備注 |
|---|---|---|
path |
結(jié)合注冊時的前綴共同構(gòu)成接口URI路徑 | 用于g.Meta標(biāo)識接口元數(shù)據(jù) |
tags |
接口所屬的標(biāo)簽，用于接口分類 | 用于g.Meta標(biāo)識接口元數(shù)據(jù) |
method |
接口的請求方式：GET/PUT/POST/DELETE...(不區(qū)分大小寫) |
用于g.Meta標(biāo)識接口元數(shù)據(jù) |
deprecated |
標(biāo)記該接口廢棄 | 用于g.Meta標(biāo)識接口元數(shù)據(jù) |
summary |
接口/參數(shù)概要描述 | 縮寫sm |
description |
接口/參數(shù)詳細(xì)描述 | 縮寫dc |
in |
參數(shù)的提交方式 | header/path/query/cookie |
default |
參數(shù)的默認(rèn)值 | 縮寫d |
mime |
接口的MIME類型，例如multipart/form-data一般是全局設(shè)置，默認(rèn)為 |
用于g.Meta標(biāo)識接口元數(shù)據(jù) |
type |
參數(shù)的類型，一般不需要設(shè)置，特殊參數(shù)需要手動設(shè)置，例如file |
僅用于參數(shù)屬性 |
四、擴(kuò)展OpenAPIv3信息
核心的接口信息已經(jīng)自動生成，如果開發(fā)者想要更進(jìn)一步完善接口信息，可以通過?s.GetOpenApi()?接口獲取到?OpenAPIv3?的結(jié)構(gòu)體對象，并手動填充對應(yīng)的屬性內(nèi)容即可。我們來看一個示例，在該示例中，我們將接口中的標(biāo)簽進(jìn)行了自定義的排序，并且增加了對每個標(biāo)簽的詳細(xì)描述：
我們可以發(fā)現(xiàn)通過通用的?OpenAPIv3?對象我們可以自定義修改其內(nèi)容，并且根據(jù)它生成其他各種自定義類型的接口文檔。
五、常見問題
1、如何實現(xiàn)文件上傳的接口定義？
- 參數(shù)接收的數(shù)據(jù)類型使用?
*ghttp.UploadFile? - 如果需要接口文檔也支持文件類型，那么參數(shù)的標(biāo)簽中設(shè)置?
type?為?file?類型
當(dāng)前文章：創(chuàng)新互聯(lián)GoFrame教程：GoFrameWEB服務(wù)開發(fā)-接口文檔
網(wǎng)站地址：http://www.dlmjj.cn/article/dpedjoe.html
