一、下載go-swagger
go-swagger 官方下載
根據不同個的操作系統選擇對應的
二、添加環境變量
2.1 window
swagger_windows_amd64.exe
將swagger_windows_amd64.exe 重命名 成 swagger.exe
然后將該軟件放到$GOROOT/bin 中
2.2 linux
swagger_linux_amd64
重命名成 swagger
然后 將 軟件放入$GOROOT/bin 目錄下
mv swagger $GOROOT/bin/
三、go-swagger 使用
- 進入自己項目的根目錄
swagger 會自己尋找main 包的
- 執行命令
swagger generate spec -o ./swagger.json // 根據swagger規范 創建 swagger.json 規范文檔
swagger serve -F=swagger swagger.json // 啟動一個http 服務同時將json文檔放入http://petstore.swagger.io 執行
四、關於swagger-UI 的頁面
如果你想要 petstore.swagger.io 的那種頁面 ，你可以自己下載 https://github.com/swagger-api/swagger-ui ,
下載好后進入dist 頁面執行運行index.html 即可
五、go-swagger 規范
// swagger:operation PUT /api/v1/addr/update/{id} addr del
// ---
// summary: 修改用戶地址
// description: 修改指定用戶的addr
// parameters:
// - name: token
// in: header
// description: token
// type: string
// required: true
// - name: id
// in: path
// description: 地址id
// type: string
// required: true
// - name: addr
// in: body
// description: addr
// type: string
// required: true
// responses:
// 200: repoResp
// 400: badReq
你可以將上面的規范放在go源碼中每個controller 函數 前面
解釋
// swagger:operaion [請求方式(可以是GET\PUT\DELETE\POST\PATCH)] [url:請求地址] [tag] [operation id] （同一標簽的屬於同一類，）
// --- 這個部分下面是YAML格式的swagger規范.確保您的縮進是一致的和正確的
// summary: 標題
// description: 描述
// parametres: 下面是參數了
// - name: 參數名
in: [header|body|query|path] 參數的位置 header和body 之http的header和body 位置。 query 是http://url?query path 就是url 里面的替換信息
description: 描述
type: 類型
required: 是否必須
// responses: 響應
// 200：
// 404：