Slate

Slate can help you build beautiful static documentation for your API.

特性

  • 简洁、直观的设计

在Slate中，API的描述在文档的左侧，所有代码示例都在右侧。灵感来自Stripe和PayPal的API文档。Slate是响应式的，因此在平板电脑、手机甚至印刷品上都很好看。

  • 一个页面上的所有东西

你的用户必须搜索一百万页才能找到他们想要的东西的日子已经一去不复返了。Slate将整个文档放在一个页面上。不过，我们并没有牺牲可链接性。在滚动时，浏览器的哈希值将更新到最近的标头，因此链接到文档中的某个特定点仍然很自然和容易。

  • Slate仅仅是打了折扣

当你用Slate写文档时，你只是打了折扣，这样编辑和理解起来就很简单。所有内容都是用Markdown编写的——甚至代码示例也只是Markdown代码块。

  • 用多种语言编写代码示例

如果你的API有多种编程语言的绑定，你可以很容易地在选项卡中进行切换。在您的文档中，您将通过在每个代码块顶部指定语言名称来区分不同的语言，就像使用GitHub调味的Markdown一样。

  • 超过100种语言的开箱即用语法高亮显示，不需要配置。

  • 在页面的最左边自动平滑地滚动目录。

当您滚动时，它会显示您在文档中的当前位置。快,太。我们在TripIt使用Slate为我们的新API构建文档，我们的目录有超过180个条目。我们已经确保性能保持良好，即使对于较大的文档也是如此。

  • 让您的用户为您更新文档

默认情况下，您的板生成文档托管在一个公共GitHub存储库中。这不仅意味着您可以免费使用GitHub页面托管您的文档，而且还可以让其他开发人员在发现拼写错误或其他问题时向您的文档发出拉请求变得简单。当然，如果您不想使用GitHub，也欢迎您将文档放在其他地方。

  • RTL支持RTL语言(如阿拉伯语、波斯语(波斯语)、希伯来语等)从右到左的布局。

  • 开始使用Slate是非常容易的!只需派生这个存储库并遵循下面的说明。

或者，如果您想了解Slate的功能，可以查看一下文档示例。

安装

准备

  • macos 系统

  • ruby

$ ruby --version
ruby 2.3.7p456 (2018-03-28 revision 63024) [universal.x86_64-darwin17]

调整 ruby 源

gem sources --add https://rubygems.org/ --remove  https://gems.ruby-china.org/

如果没有翻墙，可设置为：

gem sources --add https://ruby.taobao.org/ --remove https://rubygems.org/
  • Bundler
sudo gem install bundler

安装日志

Successfully installed bundler-1.16.5
Parsing documentation for bundler-1.16.5
Done installing documentation for bundler after 4 seconds
1 gem installed

下载

$   git clone https://github.com/lord/slate.git

ps: 这里只是演示，实际操作你可以将这个项目 fork 然后修改。

运行

$   cd slate
$   bundle install
$   bundle exec middleman server

访问

浏览器打开 http://localhost:4567

Slate

参考资料

https://github.com/lord/slate

https://www.gaott.info/writing-perfect-http-api-doc-by-slate/