如何使用swagger设计出漂亮的RESTful API

按照现在的趋势，前后端分离几乎已经是业界对开发和部署方式所达成的一种共识, 后台只负责数据的提供和计算，而完全不处理展现。而前端则负责拿到数据，组织数据并展现的工作。这样结构清晰，关注点分离，前后端会变得相对独立并松耦合。而前段和后端对待的契约就是API设计文档, 有了API的设计文档过后, 后端依据设计文件开发后端程序, 前段根据API设计文档模拟服务器,开发前段页面。而Swagger就是其中一种比较优秀的 RESTful API设计工具。

1 swagger 工具简介

swagger是一个RESTful API 的设计工具，官方提供3种工具：

1. swagger-editor 在线编辑器，同时提供编辑-展现-客户端-服务端代码的生成

2. swagger-ui 展示工具，将编辑器定义好的json描述文件友好展示的工具。

3. 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文件