按照现在的趋势,前后端分离几乎已经是业界对开发和部署方式所达成的一种共识, 后台只负责数据的提供和计算,而完全不处理展现。而前端则负责拿到数据,组织数据并展现的工作。这样结构清晰,关注点分离,前后端会变得相对独立并松耦合。而前段和后端对待的契约就是API设计文档, 有了API的设计文档过后, 后端依据设计文件开发后端程序, 前段根据API设计文档模拟服务器,开发前段页面。而Swagger就是其中一种比较优秀的 RESTful API设计工具。
1 swagger 工具简介
swagger是一个RESTful API 的设计工具,官方提供3种工具:
-
swagger-editor 在线编辑器,同时提供编辑-展现-客户端-服务端代码的生成
-
swagger-ui 展示工具,将编辑器定义好的json描述文件友好展示的工具。
-
swagger-codegen 生成服务端和客户端的代码。
因为swagger-editor集成了swagger-codegen功能,因此我们仅需要使用swagger-editor和swagger-ui就够了。
2 编辑器(editor)
可以使用在线编辑器,而由于网络原因, 往往不能很好的使用swagger提供的在线编辑器,然而这个在线编辑器也可以本地部署,其次有很多编辑器也有swagger的插件, 通过按照swagger插件,我们也可以配置出一个swagger的编辑器。有了编辑器后,我们需要熟悉使用swagger来设计API的一些语法。
2.1 部署本地编辑器
安装docker,配置镜像加速,然后拉去镜像到本地运行
docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/swagger-editor
2.2 使用本地编辑器
推荐使用vscode作为编辑器, 安装vscode的Swagger View插件 就可以打造一个 swagger的编辑器了采用yaml编写,然后使用Swagger Preview 查看预览。
2.3 swagger2.0语法
- 格式
采用json, 因为yaml是json的一个超集,因此也可以使用。通常情况我们通过yaml来完成编辑,最后通过编辑器导出为json文件。
- 文件结构
为一个单独的文件,但是其中definitions部分可以被抽出来为一个独立文件,通过$ref进行引用,按照惯例,这个文件应该被命名为 swagger.json
- 数据类型
用于描述一个数据的数据类型,对象定义时使用。
- 规范
规范也就是语法,会安装此规范来编写API设计文档。以下列出了所有需要的关键字段
3 渲染器(ui)
swagger-ui的使用很简单swager-ui官方文档
3.1 HTML文档渲染
渲染器使用官方的swagger-ui,这里我们需要一个web服务器,用来渲染我们刚才编辑完成的api 设计文档。这里一般使用node 的 express为web框架来做这个简单的web服务器
3.2 PDF文档渲染
将API设计文档渲染成PDF, 流程是这样: swagger.yaml —> asciiDoc—> pdf
- 使用swagger2markup来生成asciiDoc格式的文档
下载swagger2markup工具,下载地址,选择你想要的版本下载
使用工具生成asciiDoc, -i指定swagger.yaml的位置, -f指定输出文件名称:
java -jar swagger2markup-cli-1.1.0.jar convert -i ~/PycharmProjects/doc/api_design/swagger.yaml -f asiidoc/swagger
- 使用asciidoctor来将asciiDoc换换成PDF
这是一个ruby写的工具,我本地不打算部署ruby环境,因此在找一个docker镜像:madduci/docker-asciidoctor-pdf 由于访问dockerhub的镜像速度非常慢,因此我将该工具的使用说明复制了下来,镜像使用说明
Docker Image exposing asciidoctor-pdf as entrypoint and /document as
mounted volume where to build the file To build your own documents as
PDF, simply run the container as: docker run
–rm-v/path/to/your/document/folder/:/document/madduci/docker-asciidoctor-pdf
/document/your_document.adoc If you want to use some custom styles
just run it as docker run –rm
-/path/to/your/document/folder/:/document/ madduci/ docker-asciidoctor-pdf -a pdf-stylesdir=/document/resources/themes -a
pdf-style=your_style -a pdf-fontsdir=/document/resources/fonts
/document/your_document.adoc and it will generate the pdf in the
mounted volume /document
这工具在生成含有中文的pdf文档时有字体问题,因此我修改了字体为微软雅黑字体,以下是修改方法:
- 添加雅黑字体到当前的Fonts文件夹下面,这里需要标准字体和粗体, 而默认提供的字体只有这些默认提供的字体
➜ asiidoc ls Fonts |grep -i 'yahei'
Microsoft Yahei.ttf
yahei.ttf
yahei_bold.ttf
- 修改主题配置default-theme.yml的Noto Serif字段,使用该字体:
配置文件下载地址默认配置文件下载地址
Noto Serif:
normal: yahei.ttf
bold: yahei_bold.ttf
italic: yahei.ttf
bold_italic: yahei_bold.tt
最后把我们生成好的swagger.adoc, 主题配置文件,字体 放在一个目录下,挂载到docker里面去:
➜ Downloads ls asiidoc
Fonts swagger.adoc themes
docker run --rm -v $(pwd)/asiidoc/:/document/ madduci/docker-asciidoctor-pdf -a pdf-fontsdir=/document/Fonts -a pdf-stylesdir=/document/themes /document/swagger.adoc
最后查看asiidoc下面就会有生成的pdf文件