Golang項目自動生成swagger格式接口文檔方法（一）
swag工具介紹和安裝
Swag是一款可以將Go的注釋轉(zhuǎn)換為Swagger2.0格式文檔的工具，生成接口文檔用到的注釋需要按照swag要求的格式書寫。
使用go install方式下載安裝swag
也可以從github的release頁面下載編譯好的二進制文件，以1.8.10版本為例：
在包含main.go文件的項目根目錄運行swag init將會解析注釋并生成文件（docs文件夾），修改對應(yīng)注釋后再次運行swag ini即可：
使用swag fmt可以格式化SWAG注釋：
符合swag要求的API通用注釋寫法
在main.go的main方法添加API通用注釋
更多通用注釋字段說明和示例：
注釋 | 說明 | 示例 |
title | 必填 應(yīng)用程序的名稱。 | // @title Swagger Example API |
version | 必填 提供應(yīng)用程序API的版本。 | // @version 1.0 |
description | 應(yīng)用程序的簡短描述。 | // @description This is a sample server celler server. |
tag.name | 標(biāo)簽的名稱。 | // @tag.name This is the name of the tag |
tag.description | 標(biāo)簽的描述。 | // @tag.description Cool Description |
tag.docs.url | 標(biāo)簽的外部文檔的URL。 | // @tag.docs.url ??https://example.com?? |
tag.docs.description | 標(biāo)簽的外部文檔說明。 | // @tag.docs.description Best example documentation |
termsOfService | API的服務(wù)條款。 | // @termsOfService ??http://swagger.io/terms/?? |
contact.name | 公開的API的聯(lián)系信息。 | // @contact.name API Support |
contact.url | 聯(lián)系信息的URL。 必須采用網(wǎng)址格式。 | // @contact.url ??http://www.swagger.io/support?? |
contact.email | 聯(lián)系人/組織的電子郵件地址。 必須采用電子郵件地址的格式。 | // @contact.email support@swagger.io |
license.name | 必填 用于API的許可證名稱。 | // @license.name Apache 2.0 |
license.url | 用于API的許可證的URL。 必須采用網(wǎng)址格式。 | // @license.url ??http://www.apache.org/licenses/LICENSE-2.0.html?? |
host | 運行API的主機（主機名或IP地址）。 | // @host localhost:8080 |
BasePath | 運行API的基本路徑。 | // @BasePath /api/v1 |
accept | API 可以使用的 MIME 類型列表。 請注意，Accept 僅影響具有請求正文的操作，例如 POST、PUT 和 PATCH。 值必須如“Mime類型”中所述。 | // @accept json |
produce | API可以生成的MIME類型的列表。值必須如“Mime類型”中所述。 | // @produce json |
query.collection.format | 請求URI query里數(shù)組參數(shù)的默認(rèn)格式：csv，multi，pipes，tsv，ssv。 如果未設(shè)置，則默認(rèn)為csv。 | // @query.collection.format multi |
schemes | 用空格分隔的請求的傳輸協(xié)議。 | // @schemes http https |
externalDocs.description | Description of the external document. | // @externalDocs.description OpenAPI |
externalDocs.url | URL of the external document. | // @externalDocs.url ??https://swagger.io/resources/open-api/?? |
x-name | 擴展的鍵必須以x-開頭，并且只能使用json值 | // @x-example-key {"key": "value"} |
符合swag要求的具體API注釋
在接口的handler方法中添加具體的API注釋。
參數(shù)注釋和返回注釋支持結(jié)構(gòu)體，本例中用到的結(jié)構(gòu)體在param包下面，內(nèi)容如下：
更多注釋字段說明：
注釋 | 描述 |
description | 操作行為的詳細(xì)說明。 |
description.markdown | 應(yīng)用程序的簡短描述。該描述將從名為endpointname.md的文件中讀取。 |
id | 用于標(biāo)識操作的唯一字符串。在所有API操作中必須唯一。 |
tags | 每個API操作的標(biāo)簽列表，以逗號分隔。 |
summary | 該操作的簡短摘要。 |
accept | API 可以使用的 MIME 類型列表。 請注意，Accept 僅影響具有請求正文的操作，例如 POST、PUT 和 PATCH。 值必須如“Mime類型”中所述。 |
produce | API可以生成的MIME類型的列表。值必須如“Mime類型”中所述。 |
param | 用空格分隔的參數(shù)。param name,param type,data type,is mandatory?,comment attribute(optional) |
security | 每個API操作的安全性。 |
success | 以空格分隔的成功響應(yīng)。return code,{param type},data type,comment |
failure | 以空格分隔的故障響應(yīng)。return code,{param type},data type,comment |
response | 與success、failure作用相同 |
header | 以空格分隔的頭字段。 return code,{param type},data type,comment |
router | 以空格分隔的路徑定義。 path,[httpMethod] |
x-name | 擴展字段必須以x-開頭，并且只能使用json值。 |
生成接口文檔
按照swag要求寫好注釋后，執(zhí)行如下命令生成文檔。
會在根目錄生成docs文件夾，里面包含swagger.json,、swagger.yaml和doc.go三個文件。
