前言
今天在网上发现了个不错的开源的接口文档工具slate,研究了一下并学习了一下如何安装并使用它,开始的时候用的是原生的方式安装使用的,但有些麻烦,所以试着用docker的方案安装并记录了一下安装的过程分亨出来
一、Slate是什么?
Slate 可帮助您创建美观、智能、响应迅速的 API 文档。
二、Slate特点
- 简洁、直观的设计——使用 Slate,你的 API 描述在文档的左侧,所有的代码示例都在右侧。受到 Stripe 和 PayPal 的
API 文档的启发。 Slate 响应迅速,因此在平板电脑、手机甚至印刷品上看起来都很棒。 - 一切都在一个页面上——用户必须搜索一百万个页面才能找到他们想要的东西的日子已经一去不复返了。 Slate
将整个文档放在一个页面上。不过,我们并没有牺牲可链接性。当您滚动时,浏览器的哈希值将更新为最近的标题,因此链接到文档中的特定点仍然很自然且容易。 - Slate 就是 Markdown — 当您使用 Slate 编写文档时,您只是在编写
Markdown,这使得编辑和理解变得简单。一切都是用 Markdown 编写的——甚至代码示例也只是 Markdown 代码块。 - 用多种语言编写代码示例——如果您的 API
绑定了多种编程语言,您可以轻松地放入选项卡以在它们之间切换。在您的文档中,您将通过在每个代码块的顶部指定语言名称来区分不同的语言,就像使用
GitHub Flavored Markdown 一样。 - 开箱即用的语法高亮显示超过 100 种语言,无需配置。
- 页面最左侧的自动平滑滚动目录。当您滚动时,它会显示您在文档中的当前位置。它也很快。我们在 TripIt 使用 Slate 为我们的新
API 构建文档,其中我们的目录有 180 多个条目。我们确保即使对于较大的文档,性能也能保持出色。 - 让您的用户为您更新文档 — 默认情况下,您的 Slate 生成的文档托管在公共 GitHub 存储库中。这不仅意味着您可以使用
GitHub Pages
免费托管您的文档,而且还可以让其他开发人员在发现拼写错误或其他问题时轻松地向您的文档提出拉取请求。当然,如果您不想使用
GitHub,也欢迎您在其他地方托管您的文档。 - RTL 支持 RTL 语言的完全从右到左布局,例如阿拉伯语、波斯语(波斯语)、希伯来语等。
开始使用 Slate 非常简单!只需按下上方绿色的“使用此模板”按钮,然后按照以下说明进行操作
三、Docker方式安装Slate步骤
1. 在 Github 上 fork 这个存储库
。
2. clone Slate到本地
git clone https://github.com/YOURUSERNAME/slate.git
YOURUSERNAME 代表的是你的github 的帐号
3. 进入克隆后的代码目录
cd slate
4. 获取 slate 映像或为存储库构建docker 映像
docker pull slatedocs/slate
或
docker build . -t slatedocs/slate
5. 用 Docker构建slate站点
docker run --rm --name slate -v $(pwd)/build:/srv/slate/build -v $(pwd)/source:/srv/slate/source slatedocs/slate build
6. 运行Slate服务
docker run --rm --name slate -p 4567:4567 -v $(pwd)/source:/srv/slate/source slatedocs/slate serve
## ```7. 访问slate
```bash
http://localhost:4567
总结
Slate让我们直接可以用Markdown文档写接口文档,非常不错,有时间了大家可以试试