转载

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

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

注意点

：

对于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文件的名称来维护这个文档的版本，从而快速做到不同版本文档的想法。保留历史。

原文 https://studygolang.com/articles/18175

正文到此结束

所属分类：软件架构编程技术

本文标签： GitHub schema 自动生成 web git 安装 Google ORM 目录 ip cat API 开发 message 微服务自动化产品 Facebook REST 下载数据库访问 cmd 数据库数据 json 文章模型测试 description 开发者程序员 ACE id 协议 UI App http 服务端编译 js 代码 src IO 服务器 https 配置
版权声明： 本文为互联网转载文章，出处已在文章中说明(部分除外)。如果侵权，请联系本站长删除，谢谢。
本文海报： 生成海报一生成海报二

其他链接

关于本站

本站定位：个人技术类博客

本站作用：写博客、记日志、闲聊扯淡鼓捣技术。

问题交流

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

1 swagger简介

2 自动化文档例子

2.1 创建工程并下载goswagger

2.2 编译安装swagger

2.3 创建api描述yml文件

2.4 运行api文档服务

验证yml文件定义是否有问题

运行doc的文档服务

3 为啥要文档自动化

热门推荐

相关文章

说给你听

本文目录

随机标签

书籍教程

近期评论

网站信息

其他链接

关于本站

问题交流