使用go chassis管理Restful API文檔

做爲一名開發者，可能常常遇到這種問題，項目進度太緊，當你在編寫一個Rest 服務時只能將時間都放在編碼上，文檔基本靠口口相傳。

做爲一個團隊管理者，API文檔優先很是重要，好比你須要去審批API的設計合理性，隨時查看現存的接口文檔，而且參與設計新的API。

多個團隊間有大量的微服務，每一個微服務對外暴露rest API 都須要文檔，沒有一個統一的管理系統查看這些服務的API描述文檔。讓溝通效率變得低下

若是一開始就把大量時間放在這種文檔編寫上，顯然效率是低下的。若是你使用的是gRPC，那麼管理API會方便些，可是依然缺乏一箇中心的管理處可以隨時看到不一樣服務的API。

使用Service Center做爲註冊中心

使用service center除了能夠管理異構的註冊中心，他還擁有管理服務API文檔的能力，支持經過API本身上傳，而使用go chassis開發微服務，用戶則無需關心這個過程，你只須要編寫rest服務，go chassis將在每次啓動時自動生成API文檔並上傳到服務中心，這樣登陸到系統的人就能夠看到每一個服務的API文檔，一目瞭然。

如何生成API文檔

文檔是在編寫完API接口並運行服務後自動生成的

1. 參考此文旦安裝go chassis

https://go-chassis.readthedocs.io/en/latest/getstarted/install.html

2. 咱們如今使用go chassis，開編寫一個服務，完整例子。

首先編寫API，定義好API已經對應的方法

type RestFulHello struct {}

func (r *RestFulHello) Sayhello(b *restful.Context) {
    b.Write([]byte("get user id: " + b.ReadPathParameter("userid")))
}func (s *RestFulHello) URLPatterns() []restful.Route {
    return []restful.RouteSpec{
        {http.MethodGet, "/sayhello/{userid}", "Sayhello"},
    }
}
複製代碼

將此結構體註冊到go chassis

chassis.RegisterSchema("rest", &RestFulHello{})複製代碼

編寫最基本的配置信息，包括監聽端口和service center地址

cse:
  service:
    registry:
      address: http://127.0.0.1:30100 
  protocols: # what kind of server you want to launch
    rest: #launch a http server
      listenAddress: 127.0.0.1:5001複製代碼

爲服務取名字

service_description:
  name: RESTServer # name your provider複製代碼

最後在main函數中啓動服務

func main() {
    //start all server you register in server/schemas.
    if err := chassis.Init(); err != nil {
        lager.Logger.Error("Init failed.", err)
        return
    }
    chassis.Run()
}複製代碼

最後

go build main.go

./main

查看文檔

本地

文檔會生成在運行目錄下的 conf/RESTServer/schema/RESTServer.yaml

將內容複製到http://editor.swagger.io/，就能夠看到文檔了

Service center

能夠在service center UI中下載該文檔

訪問127.0.0.1:30103，點擊services，並點擊對應的微服務

最後點擊schema tab就能夠下載API文檔說明

打開下載的文檔，就能看到這個服務的API描述了

有了這種透明的文檔生成機制，go chassis增強了開發的效率，並加強了文檔管理。

項目地址：

https://github.com/go-chassis/go-chassis