阅读 364

使用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


关注下面的标签,发现更多相似文章
评论