slate api_使用Slate编写API文档

slate api

So you’ve built yourself an API. Perhaps it’s RESTful, RESTlike or something else entirely. You’ve implemented authentication – be it using OAuth, HTTP Basic Auth or JSON Web Tokens. You’ve fashioned your responses using JSON, maybe XML, or even something else. Your unit and integration tests are passing, you may have a third-party service such a Runscope testing it periodically, or using JSON or XML schemas to validate your responses.

因此，您已经构建了自己的API。 也许是REST ful ， 类似 REST或其他任何东西。 您已经实现了身份验证-使用OAuth，HTTP基本身份验证或JSON Web令牌进行身份验证。 您已经使用JSON(也许是XML，甚至其他方式)来构建响应。 您的单元测试和集成测试通过了，您可能需要第三方服务(例如Runscope)对其进行定期测试，或者使用JSON或XML模式来验证您的响应。

There’s one more thing, however.

但是，还有一件事。

Thing is, an API is only as good as its documentation. That applies if it’s for internal use only – perhaps it’s for a JavaScript-based one-page app, or a mobile application – but even more so if it’s for public consumption.

事实是，API仅与其文档一样好。 如果仅供内部使用(适用于基于JavaScript的一页应用程序或移动应用程序)，则适用此规则；如果供公众使用，则更是如此。

There are a number of ways in which you can put together your documentation. For the purposes of this article I’ll assume it’s web-based, whether it’s publicly available over the internet or privately held on a company intranet.

您可以采用多种方法来整理文档。 出于本文的目的，我将假定它是基于Web的，无论它是通过Internet公开提供还是公司内部网上的私有股份。

You could of course hand-code it in HTML. You could use a paid service such as Readme.io. There are even tools to help automatically generate API documentation from source-code such as Doxygen and API Blueprint, or for creating dynamic docs; such as Swagger.

您当然可以用HTML手工编码。 您可以使用诸如Readme.io之类的付费服务。 甚至还有一些工具可帮助自动从源代码(例如Doxygen和API Blueprint)生成API文档，或用于创建动态文档。 如Swagger 。

Another option is Slate. Slate allows you to write your API documentation by hand using markdown, which it will then package up as a pre-styled static HTML site for you. Because it generates static HTML, hosting is straightforward – in particular, it’s a breeze to host with Github Pages. Let’s take a look at how it works, and go through an example from installation through to deployment.

另一种选择是Slate 。 Slate允许您使用markdown手工编写API文档，然后将其打包为一个预先样式化的静态HTML网站。 由于托管可以生成静态HTML，因此托管非常简单-特别是托管Github Pages轻而易举。 让我们看一下它是如何工作的，并给出一个示例，从安装到部署。

期待什么 (What to Expect)

A picture speaks a thousand words; here’s an example, straight out-of-the-box:

图片讲一千个字； 这是一个开箱即用的示例：

To see Slate-generated documentation in the wild, check out the Travis documentation, or Mozilla’s localForage or recroom docs. You’ll find even more examples in the project’s README.

要在野外查看Slate生成的文档，请查看Travis文档或Mozilla的localForage或recroom文档。 您可以在项目的README中找到更多示例。

Essentially, what you’ll get by default is the following:

本质上，默认情况下您将获得以下内容：

• a one-page static site with JS-based documentation (using jquery.tocify.js)

  一个静态页面的静态站点，带有基于JS的文档(使用jquery.tocify.js )

• automatic Markdown parsing
  自动Markdown解析
• a customizable three-columned layout
  可定制的三列布局
• in-page search
  页内搜索
• tabbed, language-specific code samples
  选项卡式，特定于语言的代码示例
• syntax highlighting
  语法高亮

入门 (Getting Started)

先决条件 (Pre-requisites)

You’re going to need Ruby, at version 1.9.3 or newer. Head over to the documentation if you don’t already have it.

您将需要1.9.3或更高版本的Ruby。 如果还没有文档 ，请转至文档 。

You’ll also need the Bundler gem, which you can install from the command-line with the following:

您还需要Bundler gem，您可以使用以下命令从命令行安装它：

gem install bundler

You can skip this, and some of the installation steps if you use Docker; Slate ships with a Dockerfile you can use to get up-and-running quickly and easily.

如果使用Docker ，则可以跳过此步骤以及一些安装步骤； Slate随附Dockerfile，可用于快速轻松地启动和运行。

安装 (Installation)

Next, fork the Github repository.

接下来，