内容简介:在微服务的开发模式下,除了底层的socket和rpc通信模式下,其中国际标准REST API是比较流行的方式,它基于http/https协议,加上JSON作为序列化的方式结合,是这几年微服务比较流行的技术标准,同时也是微服务的标配搭配模式。不同的语言都有很多Web服务API的框架,并结合数据库访问的ORM模式下,组成API的快速开发模式,但是能结合API文档自动化,和设计,构建,测试等标准与一身的,可能就唯独swagger是个不错的选择。swagger是这样的一个产品(框架),它类似于Google的Prot
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
后台运行结果
3 为啥要文档自动化
首先,程序员本身考虑出发,程序员都不喜欢写文档,文档自动化其实是让 程序员 写代码。文档自动化是让系统自动生成文档的界面。
其次,swagger的文档自动化是系统自动生成,可以通过配置代码文件修改从而改变文档页面,便于维护和使用。
所以文档自动化其实是一个高效的,并且是在微服务开发模式下,一个比较好的工程实践。
而对于文档自动化的版本,则可以做到保留每个文档配置yml文件,并通过yml文件的名称来维护这个文档的版本,从而快速做到不同版本文档的想法。保留历史。
以上就是本文的全部内容,希望本文的内容对大家的学习或者工作能带来一定的帮助,也希望大家多多支持 码农网
猜你喜欢:- APIJSON 2.9.0 发布,自动化接口和文档
- 自动化接口和文档 APIJSON 3.0.0 发布
- Google Docs API 发布,自动化文档处理
- uliweb_apijson 0.1.0 发布,自动化接口和文档
- uliweb_apijson 0.1.0 发布,自动化接口和文档
- uliweb_apijson 0.1.2 发布,自动化接口和文档 Python 实现
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
HTML5经典实例
Christopher Schmitt、Kyle Simpson / 李强 / 中国电力出版社 / 2013-7 / 48.00元
《HTML5经典实例》对于从中级到高级的Web和移动Web开发者来说是绝佳之选,它帮助你选择对你有用的HTML5功能,并且帮助你体验其他的功能。个技巧的信息十分丰富,都包含了示例代码,并详细讨论了解决方案为何有效以及如何工作。一起来看看 《HTML5经典实例》 这本书的介绍吧!
HTML 压缩/解压工具
在线压缩/解压 HTML 代码
MD5 加密
MD5 加密工具