Go Swagger 教程：如何使用 go-swagger 創(chuàng)建 Golang API 文檔
作為一名開發(fā)人員，您可能了解記錄和組織所有 API 的重要性，并且您也知道并非每個開發(fā)人員都喜歡這個文檔部分。為此，我們需要一些可以輕松用于準備 API 文檔的工具。好吧，第一個出現(xiàn)的工具是 Swagger。
什么是招搖？
Swagger 是一組用于編寫基于 REST 的 API 的開源工具。它簡化了編寫 API 的過程，指定標準并提供編寫和組織可擴展 API 所需的工具。
為什么要使用招搖？
如前所述，當我們必須遵循方法論時，文檔是“必須的”。使用 swagger，我們可以通過在代碼中添加注釋來創(chuàng)建 API 文檔。
現(xiàn)在問題可能會出現(xiàn)Swagger 只是用于 API 文檔嗎？不，這不對。
借助 Swagger，我們可以為任何技術(shù)（如 Node、AngularJS、PHP 等）生成客戶端。因此，它有利于我們應(yīng)用程序的命名約定、維護最佳實踐和通用結(jié)構(gòu)。此外，它確實節(jié)省了客戶端的編碼時間。
現(xiàn)在，讓我們看看我們將在本教程中做什么。
準備好用創(chuàng)新技術(shù)徹底改變您的行業(yè)了嗎？
聯(lián)系像 Bacancy 這樣經(jīng)驗豐富的Golang 開發(fā)公司來創(chuàng)建時尚、高性能的應(yīng)用程序，讓您的競爭對手望塵莫及。
教程目標：使用 Go Swagger 的 Golang API 文檔
在本教程中，我們將使用Go swagger制作一個演示應(yīng)用程序并準備 API 文檔。觀看下面的視頻，了解我們將在本教程中構(gòu)建的內(nèi)容。
Go Swagger 示例：如何創(chuàng)建 Golang API 文檔
事不宜遲，讓我們開始編碼部分。以下是創(chuàng)建 Golang API 文檔的分步說明。
創(chuàng)建項目目錄
使用以下命令創(chuàng)建項目目錄。
mkdir goswaggerCD 飄飄然去 mod 初始化 goswagger
安裝招搖
下載_url=$(curl -s https://api.github.com/repos/go-swagger/go-swagger/releases/latest | \
jq -r '.資產(chǎn)[] | 選擇(.name | 包含("'"$(uname | tr '[:upper:]' '[:lower:]')"'_amd64")) | .browser_download_url')curl -o /usr/local/bin/swagger -L'#' "$download_url"chmod +x /usr/local/bin/swagger
下載依賴
接下來，我們將下載所需的依賴項
對于這個演示，我們將使用：
Mux：處理http請求和路由
命令：
去獲取 github.com/gorilla/mux
Swagger：處理 swagger 文檔
命令：
去獲取 github.com/go-openapi/runtime/middleware
MySQL：處理 MySQL 查詢
命令：
github.com/go-sql-driver/mysql去獲取 github.com/jmoiron/sqlx
從根目錄導(dǎo)入數(shù)據(jù)庫 company.sql
在根目錄下創(chuàng)建main.go。建立數(shù)據(jù)庫連接、API 路由和 Swagger 文檔。
r := mux.NewRouter()
dbsqlx := 配置.ConnectDBSqlx()
hsqlx := 控制器.NewBaseHandlerSqlx(dbsqlx)
公司 := r.PathPrefix("/admin/company").Subrouter()
company.HandleFunc("/", hsqlx.PostCompanySqlx).Methods("POST")
公司.HandleFunc("/", hsqlx.GetCompaniesSqlx).Methods("GET")
company.HandleFunc("/{id}", hsqlx.EditCompany).Methods("PUT")
company.HandleFunc("/{id}", hsqlx.DeleteCompany).Methods("DELETE")
使用 Go Swagger 編寫文檔
現(xiàn)在，讓我們看看如何使用 Swagger 進行文檔化。它將由基本配置、模型和 API 路由組成。
基本配置
// 公司 API://版本：0.0.1// 標題：Company Api// 方案：http, https// 主機：localhost:5000// 基本路徑：/// 產(chǎn)生：// - 應(yīng)用程序/json//// 安全定義：// 接口密鑰：// 類型：apiKey// 在：標題// 名稱：授權(quán)//招搖：元包控制器
對于安全定義，我們可以使用 API 密鑰，它可以為每個 API 進行驗證。
楷模
為我們的 API 的請求和響應(yīng)創(chuàng)建模型。下面是一些帶有 swagger 注釋的結(jié)構(gòu)示例。我們可以為每個字段添加名稱、類型、模式、必需和描述。
類型 ReqAddCompany 結(jié)構(gòu) {
// 公司名稱
// 輸入：字符串
名稱字符串 `json:"name"validate:"required,min=2,max=100,alpha_space"`
// 公司狀況
// 輸入：int64
Status int64 `json:"status" validate:"required"`}// swagger:parameters admin addCompany類型 ReqCompanyBody 結(jié)構(gòu) {
// - 名稱：正文
// 在：主體
// 描述：名稱和狀態(tài)
// 模式：
// 類型：對象
// "$ref": "#/definitions/ReqAddCompany"
// 必需：真
正文 ReqAddCompany `json:"body"`}// swagger:模型公司類型公司結(jié)構(gòu){
//公司ID
// 輸入：int64
ID int64 `json:"id"`
// 公司名稱
// 輸入：字符串
名稱字符串 `json:"name"`
// 公司狀況
// 輸入：int64
狀態(tài) int64 `json:"status"`}// swagger:model CommonError類型 CommonError 結(jié)構(gòu) {
// 錯誤狀態(tài)
// 輸入：int64
狀態(tài) int64 `json:"status"`
// 錯誤信息
// 輸入：字符串
消息字符串 `json:"message"`}
API路由
我們可以為每條路線添加 swagger 注釋。如果需要，我們可以在其中指定請求和響應(yīng)模型、路由名稱、請求方法、描述和 API 密鑰。
// swagger:route GET /admin/company/ admin listCompany// 獲取公司列表//// 安全：// - api密鑰：[]// 響應(yīng)：// 401: 常見錯誤// 200: 獲取公司func (h *BaseHandlerSqlx) GetCompaniesSqlx(w http.ResponseWriter, r *http.Request) {
響應(yīng)：= GetCompanies{}
公司 := models.GetCompaniesSqlx(h.db)
響應(yīng).Status = 1
response.Message = lang.Get("成功")
response.Data = 公司
w.Header().Set("內(nèi)容類型", "application/json")
json.NewEncoder(w).編碼（響應(yīng)）}
// swagger:route POST /admin/company/ admin addCompany//創(chuàng)建一個新公司//// 安全：// - api密鑰：[]// 響應(yīng)：// 401: 常見錯誤// 200: 獲取公司func (h *BaseHandlerSqlx) PostCompanySqlx(w http.ResponseWriter, r *http.Request) {
w.Header().Set("內(nèi)容類型", "application/json")
響應(yīng)：=獲取公司{}
解碼器：= json.NewDecoder（r.Body）
var reqcompany *models.ReqCompany
錯誤 := decoder.Decode(&reqcompany)
fmt.Println(錯誤)
如果錯誤！=無{
json.NewEncoder(w).Encode(ErrHandler(lang.Get("invalid_request")))
返回
}
公司，errmessage := models.PostCompanySqlx(h.db, reqcompany)
如果錯誤消息！=“”{
json.NewEncoder(w).Encode(ErrHandler(錯誤消息))
返回
}
響應(yīng).Status = 1
response.Message = lang.Get("插入成功")
response.Data = 公司
json.NewEncoder(w).編碼（響應(yīng)）}
// swagger:route PUT /admin/company/{id} admin editCompany// 編輯公司//// 消費：// - 應(yīng)用程序/x-www-form-urlencoded// 安全：// - api密鑰：[]// 響應(yīng)：// 401: 常見錯誤// 200: 獲取公司func (h *BaseHandlerSqlx) EditCompany(w http.ResponseWriter, r *http.Request) {
r.ParseForm()
w.Header().Set("內(nèi)容類型", "application/json")
變量 := mux.Vars(r)
響應(yīng)：=獲取公司{}
id, 錯誤 := strconv.ParseInt(vars["id"], 10, 64)
如果錯誤！=無{
json.NewEncoder(w).Encode(ErrHandler(lang.Get("invalid_request")))
返回
}
var reqcompany 模型.ReqCompany
reqcompany.Status, err = strconv.ParseInt(r.FormValue("狀態(tài)"), 10, 64)
reqcompany.Name = r.FormValue("名稱")
如果錯誤！=無{
json.NewEncoder(w).Encode(ErrHandler(lang.Get("invalid_request")))
返回
}
公司，errmessage := models.EditCompany(h.db, &reqcompany, id)
如果錯誤消息！=“”{
json.NewEncoder(w).Encode(ErrHandler(錯誤消息))
返回
}
響應(yīng).Status = 1
response.Message = lang.Get("更新成功")
response.Data = 公司
json.NewEncoder(w).編碼（響應(yīng)）}
// swagger:route DELETE /admin/company/{id} admin deleteCompany// 刪除公司//// 安全：// - api密鑰：[]// 響應(yīng)：// 401: 常見錯誤// 200: 共同成功// 創(chuàng)建句柄刪除獲取公司func (h *BaseHandlerSqlx) DeleteCompany(w http.ResponseWriter, r *http.Request) {
變量 := mux.Vars(r)
errmessage := models.DeleteCompany(h.db, vars["id"])
如果錯誤消息！=“”{
json.NewEncoder(w).Encode(ErrHandler(錯誤消息))
返回
}
成功響應(yīng)：= CommonSuccess{}
成功響應(yīng).Status = 1
successresponse.Message = lang.Get("delete_success")
w.Header().Set("內(nèi)容類型", "application/json")
json.NewEncoder(w).Encode(成功響應(yīng))}
完成 api 后，我們可以在根目錄中使用以下命令從 swagger 注釋生成 swagger yaml或JSON文件。
swagger generate spec -o ./swagger.yaml –scan-models會在根目錄下
生成一個swagger.yaml文件。我們也可以用同樣的方式創(chuàng)建一個JSON文件。
使用這個文件，我們可以在main.go文件中添加文檔的路由。
// 開發(fā)者文檔
opts := middleware.SwaggerUIOpts{SpecURL: "/swagger.yaml"}
sh := middleware.SwaggerUI(opts, nil)
r.Handle("/文檔", sh)
// 共享文檔
// opts1 := middleware.RedocOpts{SpecURL: "/swagger.yaml"}
// sh1 := middleware.Redoc(opts1, nil)
// r.Handle("/docs", sh1)
完成這些步驟后，開發(fā)人員文檔將類似于下圖。
有關(guān)要與外部開發(fā)人員共享的只讀 API，請參閱以下文檔。
使用 Swagger 文檔生成客戶端
正如上面一開始提到的，Swagger 不僅僅用于 API 文檔；它還用于 API 文檔。我們還可以使用 Swagger 生成客戶端。讓我們看看下面的 AngularJS 客戶端生成示例。
示例：AngularJS 的客戶端生成。
npm 安裝 ng-swagger-gen --save-devsudo node_modules/.bin/ng-swagger-gen -i ../swagger.yaml -o 后端/src/app
它將為要包含在 Swagger 文檔中的所有 API 創(chuàng)建服務(wù)文件。同樣，您可以為其他框架和技術(shù)生成客戶端。
所以，這是關(guān)于使用 go-swagger 創(chuàng)建 Golang API 文檔。如需完整文檔，請隨時訪問 github 存儲庫：go-swagger-example
結(jié)論
我希望Go Swagger教程對您有所幫助，并消除了您對 Golang API 的 Swagger 文檔的疑慮。如果您是 Golang 愛好者，請訪問Golang 教程頁面以獲取更多此類教程并開始每天學(xué)習(xí)更多內(nèi)容！如果您有任何問題，請隨時發(fā)表評論并聯(lián)系。
有時，許多需求需要熟練、知識淵博且敬業(yè)的開發(fā)人員來完成他們的 Golang 項目。對于此類要求，建議聯(lián)系并聘請熟練的開發(fā)人員。您也在為您的項目尋找這樣的開發(fā)人員嗎？如果是，那為什么要浪費時間？立即聯(lián)系 Bacancy 以聘請具有基礎(chǔ)和高級 Golang 知識的Golang 開發(fā)人員。