【微服务】如何优雅的写文档(文档自动化swagger)

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

下载安装完成后目录结构如下

【微服务】如何优雅的写文档(文档自动化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

后台运行结果

【微服务】如何优雅的写文档(文档自动化swagger)

网页访问查看API说明

【微服务】如何优雅的写文档(文档自动化swagger)

3 为啥要文档自动化

首先,程序员本身考虑出发,程序员都不喜欢写文档,文档自动化其实是让程序员写代码。文档自动化是让系统自动生成文档的界面。

其次,swagger的文档自动化是系统自动生成,可以通过配置代码文件修改从而改变文档页面,便于维护和使用。

所以文档自动化其实是一个高效的,并且是在微服务开发模式下,一个比较好的工程实践。

而对于文档自动化的版本,则可以做到保留每个文档配置yml文件,并通过yml文件的名称来维护这个文档的版本,从而快速做到不同版本文档的想法。保留历史。

原文 

https://studygolang.com/articles/18175

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » 【微服务】如何优雅的写文档(文档自动化swagger)

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址