apache license 2.0如何使用防止法律糾紛_go語言使用Swaggo詳細教程

相信很多程序猿和我一樣不喜歡寫API文檔。寫代碼多舒服，寫文檔不僅要花費大量的時間，有時候還不能做到面面具全。但API文檔是必不可少的，相信其重要性就不用我說了，一份含糊的文檔甚至能讓前后端人員打起來。 而今天這篇博客介紹的swaggo就是讓你只需要專注于代碼就可以生成完美API文檔的工具。廢話說的有點多，我們直接看文章。

go語言中文文檔：www.topgoer.com

大概最后文檔效果是這樣的：

0c1195f0cbbba8adac6482df8b6c1df3.png

1.1.1. 關于Swaggo

或許你使用過Swagger, 而 swaggo就是代替了你手動編寫yaml的部分。只要通過一個命令就可以將注釋轉換成文檔，這讓我們可以更加專注于代碼。

目前swaggo主要實現了swagger 2.0 的以下部分功能：

  • 基本結構(Basic Structure)
  • API 地址與基本路徑(API Host and Base Path)
  • 路徑與操作 (Paths and Operations)
  • 參數描述(Describing Parameters)
  • 請求參數描述(Describing Request Body)
  • 返回描述(Describing Responses)
  • MIME 類型(MIME Types)
  • 認證(Authentication)Basic AuthenticationAPI Keys
  • 添加實例(Adding Examples)
  • 文件上傳(File Upload)
  • 枚舉(Enums)
  • 按標簽分組(Grouping Operations With Tags)
  • 擴展(Swagger Extensions)

下文內容均以gin-swaggo為例 這里是demo地址

1.1.2. 使用

安裝swag cli 及下載相關包

要使用swaggo,首先需要安裝swag cli。

    go get -u github.com/swaggo/swag/cmd/swag

然后我們還需要兩個包。

# gin-swagger 中間件go get github.com/swaggo/gin-swagger# swagger 內置文件go get github.com/swaggo/gin-swagger/swaggerFiles

在main.go內添加注釋

package mainimport (    "net/http"    "github.com/gin-gonic/gin"    _ "github.com/student/0509/docs"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles")// @title Swagger Example API// @version 1.0// @description This is a sample server celler server.// @termsOfService https://www.topgoer.com// @contact.name www.topgoer.com// @contact.url https://www.topgoer.com// @contact.email me@razeen.me// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host 127.0.0.1:8080// @BasePath /api/v1func main() {    r := gin.Default()    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))    v1 := r.Group("/api/v1")    {        v1.GET("/hello", HandleHello)        // v1.POST("/login", HandleLogin)        // v1Auth := r.Use(HandleAuth)        // {        //     v1Auth.POST("/upload", HandleUpload)        //     v1Auth.GET("/list", HandleList)        // }    }    r.Run(":8080")}

如上所示，我們需要導入

ginSwagger "github.com/swaggo/gin-swagger""github.com/swaggo/gin-swagger/swaggerFiles"

同時，添加注釋。其中：

  • titile: 文檔標題
  • version: 版本
  • description,termsOfService,contact ... 這些都是一些聲明，可不寫。
  • license.name 額，這個是必須的。
  • host,BasePath: 如果你想直接swagger調試API，這兩項需要填寫正確。前者為服務文檔的端口，ip。后者為基礎路徑，像我這里就是“/api/v1”。
  • 在原文檔中還有securityDefinitions.basic,securityDefinitions.apikey等，這些都是用來做認證的，我這里暫不展開。

到這里，我們在mian.go同目錄下執行swag init就可以自動生成文檔，如下：

E:goprojectsrcgithub.comopgoer>swag init2020/05/13 16:28:02 Generate swagger docs....2020/05/13 16:28:02 Generate general API Info, search dir:./2020/05/13 16:28:02 create docs.go at  docs/docs.go2020/05/13 16:28:02 create swagger.json at  docs/swagger.json2020/05/13 16:28:02 create swagger.yaml at  docs/swagger.yaml

然后我們在main.go導入這個自動生成的docs包，運行：

package mainimport (    "github.com/gin-gonic/gin"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles"    _ "github.com/razeencheng/demo-go/swaggo-gin/docs")// @title Swagger Example API// @version 1.0// ...
E:goprojectsrcgithub.comopgoer>go run main.go[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production. - using env:   export GIN_MODE=release - using code:  gin.SetMode(gin.ReleaseMode)[GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (3 handlers)[GIN-debug] GET    /api/v1/hello             --> main.HandleHello (3 handlers)[GIN-debug] Listening and serving HTTP on :8080

瀏覽器打開http://127.0.0.1:8080/swagger/index.html, 我們可以看到如下文檔標題已經生成。

a94cb3277734accff4c0bd273d745a5a.png

1.1.3. 在Handle函數上添加注釋

接下來，我們需要在每個路由處理函數上加上注釋，如：

package mainimport (    "net/http"    "github.com/gin-gonic/gin"    _ "github.com/student/0509/docs"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles")// @title Swagger Example API// @version 1.0// @description This is a sample server celler server.// @termsOfService https://www.topgoer.com// @contact.name www.topgoer.com// @contact.url https://www.topgoer.com// @contact.email me@razeen.me// @license.name Apache 2.0// @license.url http://www.apache.org/licenses/LICENSE-2.0.html// @host 127.0.0.1:8080// @BasePath /api/v1func main() {    r := gin.Default()    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))    v1 := r.Group("/api/v1")    {        v1.GET("/hello", HandleHello)        // v1.POST("/login", HandleLogin)        // v1Auth := r.Use(HandleAuth)        // {        //     v1Auth.POST("/upload", HandleUpload)        //     v1Auth.GET("/list", HandleList)        // }    }    r.Run(":8080")}// @Summary 測試SayHello// @Description 向你說Hello// @Tags 測試// @Accept json// @Param who query string true "人名"// @Success 200 {string} string "{"msg": "hello Razeen"}"// @Failure 400 {string} string "{"msg": "who are you"}"// @Router /hello [get]func HandleHello(c *gin.Context) {    who := c.Query("who")    if who == "" {        c.JSON(http.StatusBadRequest, gin.H{"msg": "who are u?"})        return    }    c.JSON(http.StatusOK, gin.H{"msg": "hello " + who})}

我們再次swag init, 運行一下。

9fc54cda27289cca8cebadddbab5b881.png

此時，該API的相關描述已經生成了，我們點擊Try it out還可以直接測試該API。

9d0c35f65e53e2df56a5ee4aefd5e092.png

是不是很好用，當然這并沒有結束，這些注釋字段，我們一個個解釋。

3eecd2eb6977ccc562a881871b805a92.png

這些注釋對應出現在API文檔的位置，我在上圖中已經標出，這里我們主要詳細說說下面參數：

Tags

Tags 是用來給API分組的。

Accept

接收的參數類型，支持表單(mpfd) 和 JSON(json)

Produce

返回的數據結構，一般都是json, 其他支持如下表：

Mime Type聲明application/jsonjsontext/xmlxmltext/plainplainhtmlhtmlmultipart/form-datampfdapplication/x-www-form-urlencodedx-www-form-urlencodedapplication/vnd.api+jsonjson-apiapplication/x-json-streamjson-streamapplication/octet-streamoctet-streamimage/pngpngimage/jpegjpegimage/gifgif

Param

參數，從前往后分別是：

@Param 1.參數名 2.參數類型 3.參數數據類型 4.是否必須 5.參數描述 6.其他屬性

  • 1.參數名參數名就是我們解釋參數的名字。
  • 2.參數類型參數類型主要有三種：path 該類型參數直接拼接在URL中，如Demo中HandleGetFile：// @Param id path integer true "文件ID" query 該類型參數一般是組合在URL中的，如Demo中HandleHello// @Param who query string true "人名" formData 該類型參數一般是POST,PUT方法所用，如Demo中HandleLogin// @Param user formData string true "用戶名" default(admin)
  • 3.參數數據類型數據類型主要支持一下幾種：string (string)integer (int, uint, uint32, uint64)number (float32)boolean (bool)注意，如果你是上傳文件可以使用file, 但參數類型一定是formData, 如下：// @Param file formData file true "文件"
  • 4.是否是必須表明該參數是否是必須需要的，必須的在文檔中會黑體標出，測試時必須填寫。
  • 5.參數描述就是參數的一些說明
  • 6.其他屬性除了上面這些屬性外，我們還可以為該參數填寫一些額外的屬性，如枚舉，默認值，值范圍等。如下：枚舉 // @Param enumstring query string false "string enums" Enums(A, B, C) // @Param enumint query int false "int enums" Enums(1, 2, 3) // @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3) 值添加范圍 // @Param string query string false "string valid" minlength(5) maxlength(10) // @Param int query int false "int valid" mininum(1) maxinum(10) 設置默認值 // @Param default query string false "string default" default(A) 而且這些參數是可以組合使用的，如：// @Param enumstring query string false "string enums" Enums(A, B, C) default(A) Success

指定成功響應的數據。格式為：

// @Success 1.HTTP響應碼 {2.響應參數類型} 3.響應數據類型 4.其他描述

  • 1.HTTP響應碼也就是200，400，500那些。
  • 2.響應參數類型 / 3.響應數據類型返回的數據類型，可以是自定義類型，可以是json。自定義類型在平常的使用中，我都會返回一些指定的模型序列化JSON的數據，這時，就可以這么寫：// @Success 200 {object} main.File 其中，模型直接用包名.模型即可。你會說，假如我返回模型數組怎么辦？這時你可以這么寫：// @Success 200 {anrry} main.File json將如你只是返回其他的json數據可如下寫：// @Success 200 {string} json ""
  • 4.其他描述可以添加一些說明。

Failure

? 同Success。

Router

? 指定路由與HTTP方法。格式為：

// @Router /path/to/handle [HTTP方法]

? 不用加基礎路徑哦。

1.1.4. 生成文檔與測試

其實上面已經穿插的介紹了。

在main.go下運行swag init即可生成和更新文檔。

點擊文檔中的Try it out即可測試。 如果部分API需要登陸，可以Try登陸接口即可。

1.1.5. 優化

看到這里，基本可以使用了。但文檔一般只是我們測試的時候需要，當我的產品上線后，接口文檔是不應該給用戶的，而且帶有接口文檔的包也會大很多(swaggo是直接build到二進制里的)。

想要處理這種情況，我們可以在編譯的時候優化一下，如利用build tag來控制是否編譯文檔。

在main.go聲明swagHandler,并在該參數不為空時才加入路由：

package main//...var swagHandler gin.HandlerFuncfunc main(){    // ...        if swagHandler != nil {            r.GET("/swagger/*any", swagHandler)        }    //...}

同時,我們將該參數在另外加了build tag的包中初始化。

// +build docpackage mainimport (    _ "github.com/razeencheng/demo-go/swaggo-gin/docs"    ginSwagger "github.com/swaggo/gin-swagger"    "github.com/swaggo/gin-swagger/swaggerFiles")func init() {    swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)}

之后我們就可以使用go build -tags "doc"來打包帶文檔的包，直接go build來打包不帶文檔的包。

你會發現，即使我這么小的Demo,編譯后的大小也要相差19M !

?  swaggo-gin git:(master) ? go build?  swaggo-gin git:(master) ? ll swaggo-gin-rwxr-xr-x  1 xxx  staff    15M Jan 13 00:23 swaggo-gin?  swaggo-gin git:(master) ? go build -tags "doc"?  swaggo-gin git:(master) ? ll swaggo-gin-rwxr-xr-x  1 xxx  staff    34M Jan 13 00:24 swaggo-gin

文章到這里也就結束了，完整的Demo地址在這里。

相關鏈接

  • Swaggo Github
  • Swagger

本文來自互聯網用戶投稿，該文觀點僅代表作者本人，不代表本站立場。本站僅提供信息存儲空間服務，不擁有所有權，不承擔相關法律責任。
如若轉載，請注明出處：http://www.pswp.cn/news/531866.shtml
繁體地址，請注明出處：http://hk.pswp.cn/news/531866.shtml
英文地址，請注明出處：http://en.pswp.cn/news/531866.shtml

如若內容造成侵權/違法違規/事實不符，請聯系多彩編程網進行投訴反饋email:809451989@qq.com，一經查實，立即刪除！

相關文章

靜態代碼塊，構造代碼塊，局部代碼塊演示

靜態代碼塊，構造代碼塊，局部代碼塊演示

public class Test{static int num;static int numObj;//記錄有多少個對象產生！static{//靜態代碼塊， 是用來給類進行初始化的！//num 10;num;num *12;//沒有進入靜態代碼塊之前，num的初始化值是0System.out.println(num);//main(…
閱讀更多...
android執行main函數,AndroidStudio執行main方法報錯

android執行main函數,AndroidStudio執行main方法報錯

問題：有時在開發中想直接寫一個java文件來測試一些東西，但是AndroidStudio執行的時候會報錯。代碼信息：public class HelloWorld {public static void main(String[] args) {System.out.println("HelloWorld");}}報錯信息12:04:41:…
閱讀更多...
模擬java.util.Collection一些簡單的用法

模擬java.util.Collection一些簡單的用法

/* 需求：模擬java.util.Collection一些簡單的用法！注意：java虛擬機中并沒有泛型類型的對象。泛型是通過編譯器執行一個被稱為類型擦除的前段轉換來實現的。 1）用泛型的原生類型替代泛型。 原生類型是泛型中去掉尖括號及其中的類型…
閱讀更多...
hive 導出json格式 文件_Hive 系列 之 基本操作合集

hive 導出json格式 文件_Hive 系列 之 基本操作合集

下面是本課程概覽：（1）hive系列之簡介，安裝，beeline和hiveserver2（2）hive系列之基本操作（3）hive系列之udf（4）hive系列之二級分區和動態分區&#x…
閱讀更多...
android開發自定義view倍絲曲線,從0到1Android自定義View（四）貝塞爾曲線

android開發自定義view倍絲曲線,從0到1Android自定義View（四）貝塞爾曲線

原標題：從0到1Android自定義View(四)貝塞爾曲線2017年安卓巴士全球開發者論壇-上海站作者本文由兩點水投稿，博客地址：http://www.apkbus.com/myspaceblog-911082.html前言扯來扯去，前面三篇自定義 View 文章，終于扯完了…
閱讀更多...
如何保證對象的唯一性

如何保證對象的唯一性

/* 如何保證對象的唯一性：1.不允許其他程序用new來創建該類對象。2.在該類創建一個本類實例。3.對外提供一個方法讓其他程序可以獲取該對象的引用。 */ public class Test{public static void main(String[] args){//Subject sub Subject.oSub;//這種方法不可控&am…
閱讀更多...
ios kvo 要引入_騰訊社招iOS面試記錄

ios kvo 要引入_騰訊社招iOS面試記錄

畢業好幾年了，上周發送了簡歷給騰訊，參加了騰訊面試。具體部門這邊就不說了。這次面試還是收獲到了很多。一面電話面試：面試官主要是針對iOS相關的基礎問題。先簡單自我介紹一下自己對mrc和arc的理解談談對自動釋放池的理解自動釋放池在mrc和…
閱讀更多...
動態設置html字號,動態設置html的font-size值 （適配文字大小）

動態設置html字號,動態設置html的font-size值 （適配文字大小）

PC端(function () {function setRootFontSize() {let rem, rootWidth;let rootHtml document.documentElement;//限制展現頁面的最小寬度rootWidth rootHtml.clientWidth < 1366 ? 1366 : rootHtml.clientWidth;// 19.2 設計圖尺寸寬 / 100( 設計圖的rem 100 )rem roo…
閱讀更多...
一個小例子對多態簡單的理解

一個小例子對多態簡單的理解

class Parent{int age;String name;public Parent(String name, int age){this.name name;this.age age;}public void writeWay(){System.out.println("毛筆!");}}class Child extends Parent{int age;String name;//這里只說為了說明一個問題&#xff0c;其實完全…
閱讀更多...
運行shell腳本時怎么知道jdk路徑_Shell寫腳本關于ssh執行jar包，需要刷新JDK路徑的問題...

運行shell腳本時怎么知道jdk路徑_Shell寫腳本關于ssh執行jar包，需要刷新JDK路徑的問題...

比如腳本中下面這一段ssh $i "java -jar /applog/$PROJECT/$APPNAME --server.port$SERVER_PORT >/dev/null 2>&1 &"免密登錄linux服務器&#xff0c;執行jar包&#xff0c;通過ssh執行java程序&#xff0c;涉及到一個找不到JDK路徑的問題&#xff0c;…
閱讀更多...
html 中加號的表示方法,CSS的+(加號)選擇器怎么用

html 中加號的表示方法,CSS的+(加號)選擇器怎么用

在CSS中“”符號選擇器用于選擇緊跟在指定元素之后但不在特定元素內部的元素。下面本篇文章就來具體介紹一下&#xff0c;希望對大家有所幫助。“”符號選擇器在CSS中“”符號選擇器被稱為相鄰兄弟選擇器&#xff0c;用于選取在同一父元素下的&#xff0c;緊跟指定元素之后的另…
閱讀更多...
poj 1724ROADS（bfs和dfs做法）

poj 1724ROADS（bfs和dfs做法）

1 /*2 dfs比較好想&#xff0c;就是測試數據的問題&#xff0c;導致在遍歷邊的時候要倒著遍歷才過&#xff01;3 */4 #include<iostream> 5 #include<cstdio>6 #include<cstring>7 #include<vector>8 #include<algorithm>9 #define Max 0x3f3f3f…
閱讀更多...
華為新系統 鴻蒙,旗艦CPU＋鴻蒙OS！華為Mate家族重磅新品來襲

華為新系統 鴻蒙,旗艦CPU＋鴻蒙OS！華為Mate家族重磅新品來襲

我們常說安卓平板的生態跟蘋果iPad有很大差距&#xff0c;不論是應用質量還是原生系統支持&#xff0c;蘋果都做的更好一些。可能也是因為這個原因&#xff0c;因此安卓平板&#xff0c;尤其是旗艦級別的平板至今除了三星之外&#xff0c;也就只有華為在做。作為安卓陣營兩大廠…
閱讀更多...
mysql中用來取余數的函數是_MySQL常用函數-單行處理函數-字符串處理函數(更新中...)...

mysql中用來取余數的函數是_MySQL常用函數-單行處理函數-字符串處理函數(更新中...)...

本篇文章用到的數據庫表/* SQLyog Ultimate v12.09 (64 bit) MySQL - 5.7.23-log : Database - myemployees ********************************************************************* *//*!40101 SET NAMES utf8 */;/*!40101 SET SQL_MODE*/;/*!40014 SET OLD_UNIQUE_CHECKSUN…
閱讀更多...
HDU 1024Max Sum Plus Plus(最大m字段和)

HDU 1024Max Sum Plus Plus(最大m字段和)

/* 動態轉移方程&#xff1a;dp[i][j]max(dp[i-1]a[i], max(dp[t][j-1])a[i]) (j-1<t<i) 表示的是前i個數j個字段和的最大值是多少&#xff01; */ 1 #include<iostream> 2 #include<cstdio>3 #include<cstring>4 #define N 10000 5 using nam…
閱讀更多...
html盒子模型頁面居中,【靜態頁面架構】CSS之盒子模型

html盒子模型頁面居中,【靜態頁面架構】CSS之盒子模型

CSS架構盒子模型&#xff1b;以內容區(顯示文本和圖像)內邊距(內容區至邊距的距離)邊距(內容區的邊界)外邊距(元素的邊框之間的距離)1.邊距&#xff1b;border屬性&#xff1b;簡寫屬性用來設置邊距的上(top)右(right)下(bottom)左(left)。寬度&#xff0c;顏色和樣式div{width…
閱讀更多...
最強動畫制作人書包_聲優訪談丨戀與制作人動畫中配聲優訪談——夏磊

最強動畫制作人書包_聲優訪談丨戀與制作人動畫中配聲優訪談——夏磊

親愛的制作人們&#xff1a;距離戀與制作人動畫上線還有6天&#xff01;今天的中配聲優訪談嘉賓是在動畫中為許墨獻聲的夏磊老師~固定布局 工具條上設置固定寬高背景可以設置被包含可以完美對齊背景圖和文字以及制作自…
閱讀更多...
（單例設計模式中）懶漢式與餓漢式在多線程中的不同

（單例設計模式中）懶漢式與餓漢式在多線程中的不同

/*目的&#xff1a;分析一下單例設計模式中&#xff0c;懶漢式與餓漢式在多線程中的不同&#xff01;開發時我們一般選擇餓漢式&#xff0c;因為它簡單明了&#xff0c;多線程中不會出現安全問題&#xff01;而餓漢式需要我們自己處理程序中存在的安全隱患&#xff0c;但是餓漢…
閱讀更多...
shiro修改html不生效,shiro中anon配置不生效

shiro修改html不生效,shiro中anon配置不生效

再配置shiro的時候&#xff0c;如下代碼要注意&#xff1a;1、下述代碼中必須是LinkedHashMap 而不能是HashMap。2、anon定義必須在authc之前否則anon定義不生效Beanpublic ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager){ShiroFilterFactor…
閱讀更多...
codesys com庫_CoDeSys官方系統庫在線下載，替換國內下載服務器教程

codesys com庫_CoDeSys官方系統庫在線下載，替換國內下載服務器教程

歡迎加入工控分享技術服務社區推薦閱讀Codesys學習資料大全Codesys控制器關于CANopen總線的詳細應用說明當你軟件報以下錯誤&#xff0c;你可以直接下載&#xff0c;如果下載不成功&#xff0c;可以換個網絡試一試&#xff0c;或者進行下面的操作。由于國內網絡問題&#xff0c…
閱讀更多...
最新文章

Copyright @ 2022~2023