【微服務】如何優雅的寫文件（文件自動化swagger）

Swagger · 發表 2019-02-11 23:46:50

摘要： 1 swagger簡介在微服務的開發模式下，除了底層的socket和rpc通訊模式下，其中國際標準REST API是比較流行的方式，它基於http/https協議，加上JSON作為序列化的方式結合，是這幾年微服務比較流行的技術標準，同時也是微服務的標配搭配模式。不同的語言都有很多W...

1 swagger簡介

在微服務的開發模式下，除了底層的socket和rpc通訊模式下，其中國際標準REST API是比較流行的方式，它基於http/https協議，加上JSON作為序列化的方式結合，是這幾年微服務比較流行的技術標準，同時也是微服務的標配搭配模式。

不同的語言都有很多Web服務API的框架，並結合資料庫訪問的ORM模式下，組成API的快速開發模式，但是能結合API文件自動化，和設計，構建，測試等標準與一身的，可能就唯獨swagger是個不錯的選擇。

swagger是這樣的一個產品（框架），它類似於Google的Protocol buffer（Proto）, facebook的thrift，以及grpc等客戶端和服務通訊的手段，以及服務端進行服務和返回內容的序列化，並且和這些技術框架類似，swagger定義了一套介面檔案的規範。主要內容有以下幾個方面：

設計：通過一套標準來定義設計和模型化的APIs。

構建：根據API構建生成不同語言的穩定可重用的程式碼。

文件化：幫助開發者建立api文件，即文件的自動化。

測試：可以快速的對API進行功能測試。

標準化：根據API的框架形成API的風格化。

而這篇文章，將重點進行自動化文件的API訪問docs的講解和實踐介紹，講解將採用golang的swagger框架go-swagger。

2 自動化文件例子

2.1 建立工程並下載goswagger

建立目錄goswagger並將GOPATH設定到這個目錄，並建立src目錄，並與src下面建立autodocs

go get -u github.com/go-swagger/go-swagger

下載安裝完成後目錄結構如下

注意點

：

對於golang.org的目錄庫的下載，直接找到golang的github目錄地址： https://github.com/golang

然後通過git clone下載對應的net和text到本地，並放到GOPATH目錄golang.org/x/下

2.2 編譯安裝swagger

到目錄github.com/go-swagger/go-swagger/cmd/swagger下進行go install

編譯成功後swagger可執行程式會生成到$GOPATH/bin 下面

2.3 建立api描述yml檔案

在autodocs目錄下建立api文件描述檔案autodocs.yml

---
swagger: "2.0"
info:
description: 文件自動化swagger例子配置和演示
title: 自動化文件API例子doc文件說明
version: 1.0.0
consumes:
- application/autodocs.v1+json
produces:
- application/autodocs.v1+json
schemes:
- http
paths:
/get_info:
get:
summary: '1 獲取資訊get_info'
description: '這是一個獲取資訊資料的例子，呼叫傳參可以獲取你想要的資訊,出錯的時候會有返回'
operationId: get_info
consumes:
- application/json
produces:
- application/json
parameters:
- name: name
in: query
description: 名字 
required: true
type: string
responses:
'200':
description: 成功
schema:
$ref: '#/definitions/SchemaModel'
'500':
description: 伺服器內部錯誤
schema:
$ref: '#/definitions/ErrorModel'
definitions:
SchemaModel:
type: object
properties:
id:
type: integer
ErrorModel:
type: object
properties:
message:
type: string
code:
type: integer

2.4 執行api文件服務

驗證yml檔案定義是否有問題

swagger validate autodoc.yml

執行doc的文件服務

swagger serve --host=0.0.0.0 --port=2399 --no-open autodoc.yml

後臺執行結果

網頁訪問檢視API說明

3 為啥要文件自動化

首先，程式設計師本身考慮出發，程式設計師都不喜歡寫文件，文件自動化其實是讓程式設計師寫程式碼。文件自動化是讓系統自動生成文件的介面。

其次，swagger的文件自動化是系統自動生成，可以通過配置程式碼檔案修改從而改變文件頁面，便於維護和使用。

所以文件自動化其實是一個高效的，並且是在微服務開發模式下，一個比較好的工程實踐。

而對於文件自動化的版本，則可以做到保留每個文件配置yml檔案，並通過yml檔案的名稱來維護這個文件的版本，從而快速做到不同版本文件的想法。保留歷史。