slate api_使用Slate编写API文档

痛定思痛。 2022-12-03 01:55 297阅读 0赞

slate api

So you’ve built yourself an API. Perhaps it’s REST*ful*, REST*like* 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之][Readme.io]类的付费服务。 甚至还有一些工具可帮助自动从源代码(例如[Doxygen][]和[API Blueprint)][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:

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

![API documentation created by Slate, straight out-of-the-box][API documentation created by Slate_ 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].

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

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。 如果还没有[文档][documentation] ，请转至[文档][documentation] 。

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][Slate].

接下来， [分叉][fork] [Github存储库][Slate] 。

Clone your fork of the repository to your machine:

将存储库的分支克隆到计算机上：

git clone git@github.com:[YOUR-USERNAME]/slate.git

If you take a look in the newly created `slate` folder, you should see the following structure:

如果查看新创建的`slate`文件夹，则应该看到以下结构：

![The default Slate folder structure][]

Next, `cd` into the `slate` directory and install the necessary libraries:

接下来， `cd`进入`slate`目录并安装必要的库：

bundle install

Finally, enter the following command to launch Middleman, a lightweight web server, which will listen on port 4567:

最后，输入以下命令以启动轻量级Web服务器Middleman，它将侦听端口4567：

bundle exec middleman server

If you now browse to `http://localhost:4567`, you should see the site in all its glory. You can also view the Middleman configuration by browsing to `http://localhost:4567/__middleman/`.

如果现在浏览到`http://localhost:4567` ，则应该看到该站点的所有功能。 您还可以通过浏览到`http://localhost:4567/__middleman/`来查看Middleman配置。

As well as serving up the site locally, Middleman will watch for changes and rebuild the site as required. We’ll try that out by modifying the site’s meta-data.

除了在本地提供站点服务之外，Middleman还将监视更改并根据需要重建站点。 我们将通过修改网站的元数据来进行尝试。

## 元数据和配置 **(**Meta-Data and Configuration**)** ##

Let’s start by modifying your documentation site’s title. Open up `slate/index.md`, and change the first line of the (YAML-based) configuration at the top of the file:

让我们从修改文档站点的标题开始。 打开`slate/index.md` ，并在文件顶部更改(基于YAML的)配置的第一行：

---
    title: API Reference

For example:

例如：

---
    title: MusicApp API Docs

Now go back to your browser, hit refresh and you should see the changes take effect straight away.

现在返回浏览器，单击“刷新”，您应该看到更改立即生效。

Now let’s look at the other configuration variables. If you look at the default site, you’ll find it includes three tabs sitting at the top of the right-hand column, which allow you to browse language-specific example code.

现在让我们看看其他配置变量。 如果您查看默认站点，则会发现它在右侧列的顶部包含三个选项卡，可用于浏览特定于语言的示例代码。

Out-of-the-box, those tabs are Shell, Ruby and Python:

现成的选项卡是Shell，Ruby和Python：

language_tabs:
      - shell
      - ruby
      - python

Let’s get rid of Python (no disrespect intended!) and change it to PHP:

让我们摆脱Python(不要无礼！)并将其更改为PHP：

language_tabs:
      - shell
      - ruby  
      - php

You’ll notice we’ve added PHP using lowercase letters. This is important, because the language name must exactly match the corresponding format which [Rouge][] – the syntax highlighter used by Slate – expects. However, you’ll probably want to display it in uppercase. While we’re at it, let’s change “shell” so that it displays “cURL”, and correctly capitalize Ruby. To provide an alternative “display name” for a language, simply append it after a colon, as follows:

您会注意到我们使用小写字母添加了PHP。 这很重要，因为语言名称必须与[Rouge][] (Slate使用的语法荧光笔)期望的相应格式完全匹配。 但是，您可能希望以大写形式显示它。 在此过程中，让我们更改“ shell”，使其显示“ cURL”，并正确地将Ruby大写。 要为语言提供替代的“显示名称”，只需将其附加在冒号后面，如下所示：

language_tabs:
      - shell: cURL
      - ruby: Ruby  
      - php: PHP

Again, by going to your broswer and hitting refresh you should see the changes straight away.

同样，通过浏览并单击刷新，您应该会立即看到更改。

The configuration section also allows you to add links below the menu in the left-hand column. To add a link to your client libraries, for example, modify the `toc_footers` section as follows:

配置部分还允许您在左侧列的菜单下方添加链接。 例如，要将链接添加到客户端库，请修改`toc_footers`部分，如下所示：

toc_footers:
      - <a href='#'>Sign Up for a Developer Key</a>
      - <a href='https://github.com/acme'>Client libraries</a>
      - <a href='http://github.com/tripit/slate'>Documentation Powered by Slate</a>

We’ll look at the `includes` section shortly.

我们将稍后介绍`includes`部分。

Now that we’ve configured our documentation site, it’s time to get writing.

现在我们已经配置了文档站点，是时候开始编写了。

## 编写文件 **(**Writing your Documentation**)** ##

Out-of-the-box, Slate provides a bunch of dummy content. The easiest way to get started is probably to modify that, as it will help familiarize you with Slate’s structure and style of markdown.

开箱即用，Slate提供了一堆虚拟内容。 最简单的入门方法可能是对其进行修改，因为这将有助于您熟悉Slate的减价结构和样式。

You’ll notice there are four sections, which the left-hand menu automatically picks up on. Using the JQuery TOC (Table of Contents) plugin, which will already be installed for you, it allows you to navigate between them, and will also expand the current item to show the second-level navigation.

您会注意到有四个部分，左侧菜单会自动打开这些部分。 使用已经为您安装的JQuery TOC(目录)插件，您可以在它们之间进行导航，还可以扩展当前项以显示第二级导航。

The four sections are as follows:

四个部分如下：

*  Introduction
    
    介绍
 *  Authentication
    
    认证方式
 *  Kittens
    
    小猫
 *  Errors
    
    失误

The introduction, authentication and errors section are generic enough that we probably want to keep them, albeit modified to suit our API.

简介，认证和错误部分具有足够的通用性，尽管为了适应我们的API而进行了修改，我们可能希望保留它们。

“Kittens” reflects the example entity for the dummy documentation. It’s common practice to split up your API documentation into the various entities your API supports, so let’s change “Kittens” to “Albums”, since for the purposes of this article we’re going to document a music-related API. To do so, find the following (around line 61):

“小猫”反映了虚拟文档的示例实体。 通常将API文档拆分为API支持的各种实体，因此让我们将“小猫”更改为“专辑”，因为出于本文的目的，我们将记录与音乐相关的API。 这样做，找到以下内容(第61行)：

# Kittens

Change it to:

更改为：

# Albums

You should find that simply by renaming this level-one header, the left-hand menu and the name of the auto-generated anchor should change with it.

您应该发现，只需重命名此一级标题，左侧菜单和自动生成的锚点的名称都应随之更改。

You can also modify, remove or add the second level headings, which again update the menu in its expanded form accordingly.

您还可以修改，删除或添加第二级标题，它们会相应地以展开形式再次更新菜单。

Here’s an example for our music API:

这是我们的音乐API的示例：

## Get All Albums
    	
    	```ruby
    	require 'music'
    	
    	api = Music::APIClient.authorize!('your-api-key')
    	api.albums.get
    	```
    	
    	```shell
    	curl "http://example.com/api/albums"
    	  -H "Authorization: your-api-key"
    	```
    	
    	```php
    	$client = new Acme\Music\Client('your-api-key');
    	$client->authorize();
    	$albums = $client->getAlbums();
    	```
    	
    	
    	The above command returns JSON structured like this:
    	
    	```json
    	[
    	  {
    	    "id": 1,
    	    "title": "Dubnobasswithmyheadman",
    	    "artist": "Underworld",
    	    "year": 1994
    	  },
    	  {
    	    "id": 2,
    	    "title": "ISDN",
    	    "artist": "Future Sound of London",
    	    "year": 1994
    	  }
    	]
    	```
    	
    	This endpoint retrieves all albums.

Feel free to use third-level headings and above as normal, although note that the menu only goes two-levels deep.

尽管请注意菜单仅深入两个级别，但仍可以正常使用第三级及以上标题。

As far as the body of your documentation goes, it’s largely just plain old Markdown. Take a look at the default introduction as an example, and modify it accordingly. Things get a little more complex when we start using notices and code samples, as we’ll see shortly.

就您的文档正文而言，它基本上只是普通的Markdown。 以默认介绍为例，并进行相应的修改。 当我们开始使用通知和代码示例时，事情会变得更加复杂，我们将很快看到。

## 使用包含 **(**Using Includes**)** ##

If your API documentation is going to get quite long or quite complex, keeping all of it in one file will quickly become unmanageable. However, it’s very easy to split it into multiple files.

如果您的API文档太长或太复杂，那么将所有文档保存在一个文件中将很快变得难以管理。 但是，将其拆分为多个文件非常容易。

You’ll notice that the example errors section is already situated in a separate file – you’ll find it in `includes/_errors.md`.

您会注意到示例错误部分已经位于单独的文件中–您可以在`includes/_errors.md`找到它。

Let’s create a new section, “Artists” and place it in a separate file. First, create that file as `includes/_artists.html`:

让我们创建一个新的部分“ Artists”并将其放在单独的文件中。 首先，将该文件创建为`includes/_artists.html` ：

# Artists
    
    In addition to album and track information, you can also request information about the artists.
    
    ## Getting all Artists
    
    Retrieve information about all artists using the following URL:
    
    `GET http://example.com/api/artists`
    
    ## Getting an Artist
    
    Retrieve a specific artist using the following URL:
    
    `GET http://example.com/api/artists/[ID]`
    
    <aside class="notice">
    Replace [ID] with the numeric ID of the artist
    </aside>

Now we need to tell Slate about our new section. In the configuration section at the top of `slate\index.md`, inserting the name of the file – minus the preceding underscore – placing it right before the Errors section as follows:

现在我们需要告诉Slate我们的新部分。 在`slate\index.md`顶部的配置部分中，插入文件名(减去前面的下划线)，将其放置在“错误”部分的正`slate\index.md` ，如下所示：

includes:
      - artists
      - errors

You should find that the contents of `includes/_artists.md` has been inserted just before the errors section, and that the menu has automatically been adjusted to match.

您应该发现`includes/_artists.md`的内容已在错误部分之前插入，并且菜单已自动调整为匹配。

## 快讯 **(**Alerts**)** ##

Slate comes with three “alert” styles out-of-the-box; notices, success messages and warnings. These are pictured below, in that order:

Slate开箱即用，提供三种“警报”样式。 通知，成功消息和警告。 这些按下面的顺序排列如下：

![Notices][]

To display these, insert an `<aside>` with the relevant class:

要显示这些内容，请在相关类中插入`<aside>` ：

## 桌子 **(**Tables**)** ##

Tables lend themselves well to API documentation. The out-of-the-box errors section uses a table to list HTTP response codes; chances are, you can simply modify this to suit.

表很适合API文档。 开箱即用的错误部分使用表格列出HTTP响应代码； 很有可能，您可以简单地对此进行修改以适合。

You’ll probably also want to use them to list an endpoint’s available parameters; again, the dummy content provides examples which you can simply modify.

您可能还希望使用它们列出端点的可用参数。 同样，虚拟内容提供了可以简单修改的示例。

Otherwise, in addition to writing out by hand – which is relatively simple, yet fiddly – then you could use [this online tool][].

否则，除了手动写出(相对简单但比较麻烦)之外，您还可以使用[此在线工具][this online tool] 。

## 侧边栏 **(**Sidebar**)** ##

The sidebar on the right hand side is largely made up of three separate elements:

右侧的侧边栏主要由三个独立的元素组成：

*  callouts
    
    标注
 *  language-specific example code
    
    特定于语言的示例代码
 *  sample output
    
    样本输出

A sample callout is illustrated below:

标注示例如下所示：

![An example Callout][]

To include one, which will appear in the right-hand column, use the Markdown for a blockquote:

要包括将出现在右侧列中的一个，请使用Markdown来引用块引用：

> A sample of the JSON you can expect is displayed below

To include code samples use Github-flavored markup, ensuring the language name matches one of the ones we configured earlier; if you’ve been following along, you’ll remember that for this example those keys are `shell`, `ruby` and `php`. If you try and use the “display” name, for example cURL or PHP, the tabs won’t render properly.

要包括代码示例，请使用Github风格的标记，确保语言名称与我们之前配置的语言名称之一匹配； 如果您一直在遵循，您会记住，在此示例中，这些键是`shell` ， `ruby`和`php` 。 如果尝试使用“显示”名称，例如cURL或PHP，则选项卡将无法正确显示。

For example, to display some sample PHP:

例如，显示一些示例PHP：

```php
    	<?php
    	$client = new Acme\Music\Client($apiKey);
    	$client->authorize();
    	$albums = $client->getAlbums();
    	?>
    	```

Notice that we’re including the opening and closing PHP tags; without this, the syntax highlighter doesn’t do its magic.

注意，我们包括了打开和关闭PHP标记； 没有这个，语法荧光笔就不会发挥作用。

Typically you’ll want to create samples for each of your chosen languages for each endpoint:

通常，您需要为每种端点的每种所选语言创建样本：

```shell
    	curl "http://example.com/api/albums"
    	  -H "Authorization: your-api-key"
    	```
    
    	```ruby
    	require 'music'
    	
    	api = Music::APIClient.authorize!('your-api-key')
    	api.albums.get
    	```

Provided you place your code in the relevant section, it should appear in the correct place. When users select their preferred language using the tabs, only the specified language should be displayed.

如果您将代码放在相关部分中，则它应该出现在正确的位置。 当用户使用选项卡选择首选语言时，仅应显示指定的语言。

You can also embed example responses from your API. For example, to provide an example JSON response:

您还可以嵌入来自API的示例响应。 例如，提供示例JSON响应：

```json
    	[
    	  {
    	    "id": 1,
    	    "title": "Dubnobasswithmyheadman",
    	    "artist": "Underworld",
    	    "year": 1994
    	  },
    	  {
    	    "id": 2,
    	    "title": "ISDN",
    	    "artist": "Future Sound of London",
    	    "year": 1994
    	  }
    	]
    	```

Because the `json` key doesn’t match one of the configured languages, it will be displayed on whichever tab is selected – this, of course, is what we want since the output should be the same whichever language is used to query the API.

由于`json`键与配置的语言之一不匹配，因此它将显示在选择的任何选项卡上–当然，这就是我们想要的，因为无论查询API的哪种语言，输出都应该相同。

## 其他降价促销 **(**Other Markdown**)** ##

You’ll find a comprehensive guide to the Markdown used in Slate [on the wiki][]; but as you’ll see, it’s pretty much standard Markdown, so there’s little else to learn if you’re already familiar with it.

您可以[在Wiki上的][on the wiki] Slate中找到有关Markdown的综合指南； 但是，正如您将看到的，它几乎是标准的Markdown，因此如果您已经熟悉它，则没有什么其他需要学习的东西了。

## 客制化 **(**Customizing**)** ##

The first and simplest thing you’ll probably want to tweak is the site logo. Slate comes with a placeholder image; all you need do is replace it.

您可能要调整的第一件事也是最简单的事情是站点徽标。 Slate带有占位符图像； 您需要做的就是更换它。

You’ll find it in `slate\source\images\logo.png`. The default image is 230 x 52 pixels; the default site uses a fixed width left-hand column to match, so unless you’re planning to modify that, it’s probably best to keep your image at roughly the same dimensions.

您可以在`slate\source\images\logo.png`找到它。 默认图像为230 x 52像素； 默认站点使用固定宽度的左侧列进行匹配，因此，除非您打算对其进行修改，否则最好将图像保持在大致相同的尺寸。

Beyond changing the logo image, customizing is really quite simple. Everything in the `source` directory – bar the layouts directory – everything will get copied over to the “built” version of the site. If you wish to add additional stylesheets, fonts, images or JS files, just pop them in the relevant directory.

除了更改徽标图像外，自定义实际上非常简单。 `source`目录中的所有内容(不包括布局目录)都将被复制到站点的“已构建”版本中。 如果要添加其他样式表，字体，图像或JS文件，只需将它们弹出到相关目录中即可。

You can modify the stylesheets as you wish; do note that they are in `.scss` format, so it’s probably easiest to stick to that – don’t worry about compiling them, since that’s taken care of for you. The “main” styles are in `source\stylesheets\screen.css.scss`, and you’ll find that it’s pretty well documented.

您可以根据需要修改样式表。 请注意，它们采用`.scss`格式，因此可能最容易坚持这一点–不必担心编译它们，因为这已经为您服务。 “主要”样式位于`source\stylesheets\screen.css.scss` ，并且您会发现它已被很好地记录在案。

If you want to modify the layout, you’ll find it in `source\layouts\layout.erb`. Don’t worry if you’re not too familiar with the ERB templating system; in the most part the template tags – denoted by `<%= ... =>` can be left in place; and in any case, you’ll quickly pick it up.

如果要修改布局，可以在`source\layouts\layout.erb`找到它。 如果您对ERB模板系统不太熟悉，请不要担心。 在大多数情况下，模板标记(用`<%= ... =>`可以保留在原处； 在任何情况下，您都可以快速将其拾起。

You can even rename the assets directories, should you prefer – you’ll find the appropriate configuration in `config.rb`.

如果愿意，您甚至可以重命名资产目录–您将在`config.rb`找到适当的配置。

## 建造 **(**Building**)** ##

Once you’ve modified the content, reworked the dummy content and added in your additional content, you’re ready to build.

修改内容，修改虚拟内容并添加其他内容后，就可以开始构建了。

So far we’ve used Middleman to serve the site, watch the file system and rebuild the site on demand. When it comes to building the site ready for deployment, we can use the following command:

到目前为止，我们已经使用Middleman服务该站点，监视文件系统并按需重建站点。 在构建准备部署的站点时，我们可以使用以下命令：

rake build

You should find this creates a new folder – `build` – comprising a complete, self-contained site. The markdown gets compiled into a single `index.html` file, the SASS styles get compiled, and your assets – for example the contents of the `fonts`, `images`, `javascripts` and `stylesheets` folders – get copied over from the `source` folder.

您应该找到一个新的文件夹`build`包含一个完整的自包含站点。 将markdown编译到单个`index.html`文件中，将编译SASS样式，并从`source`文件夹复制您的资产(例如， `fonts` ， `images` ， `javascripts`和`stylesheets`文件夹的内容)。

At this stage, you can simply upload the contents of the `build` folder to a webhost, use Githooks to publish it when pushed to a particular remote, or create a Grunt or Gulp task to do it automatically.

在此阶段，您可以简单地将`build`文件夹的内容上传到虚拟主机，使用Githooks在将其推送到特定远程服务器时将其发布，或者创建Grunt或Gulp任务来自动完成。

If you’d like to use Github Pages, read on because that’s made really easy for you.

如果您想使用Github Pages，请继续阅读，因为这对您来说真的很容易。

## 用Github Pages托管 **(**Hosting with Github Pages**)** ##

[Github Pages][] is optimized for use with Jekyll, but Slate works in much the same way.

[Github Pages][]经过优化，可与Jekyll一起使用，但Slate的工作方式几乎相同。

Slate comes with the [Middleman Github Pages][] plugin pre-installed. Deploying is simple:

Slate预先安装了[Middleman Github Pages][]插件。 部署很简单：

1.  Commit your changes to the source
    
    提交对源的更改
2.  Push those changes to Github
    
    将这些更改推送到Github
3.  Create a `gh-pages` branch
    
    创建一个`gh-pages`分支
4.  Run `rake publish` from the command-line
    
    从命令行运行`rake publish`

There is further information on creating Github pages [in Github’s documentation][in Github_s documentation] as well as the [Slate wiki][].

[Github的文档][in Github_s documentation]以及[Slate Wiki中][Slate wiki]提供了有关创建Github页面的更多信息。

You can also use your own custom domain; refer to the [relevant documentation][] for details.

您也可以使用自己的自定义域； [有关][relevant documentation]详细信息，请参阅[相关文档][relevant documentation] 。

Just remember you’ll need to create a `CNAME` file; for example, suppose you plan to publish your documentation at [http://docs.example.com][http_docs.example.com]. Create a file named CNAME with the following contents:

请记住，您需要创建一个`CNAME`文件。 例如，假设您打算在[http://docs.example.com][http_docs.example.com]上发布文档。 创建一个名为CNAME的文件，其内容如下：

docs.example.com

Place this file in the `source` directory. Remember that anything you put in here will automatically be copied over to your `build` folder, so it will get uploaded to Github pages for you.

将此文件放在`source`目录中。 请记住，您在此处放置的所有内容都会自动复制到您的`build`文件夹中，因此它将为您上载到Github页面。

Of course by publishing your documentation to a public Github repository, you could even turn your documentation into a community effort, allowing users to modify your documentation via direct access or pull requests. This is entirely optional, but it’s always worth bearing in mind who’ll actually be using your API.

当然，通过将文档发布到公共的Github存储库，您甚至可以将文档转变为社区的工作，从而允许用户通过直接访问或提取请求来修改您的文档。 这是完全可选的，但始终要牢记谁会真正使用您的API。

## 摘要 **(**Summary**)** ##

In this article we’ve looked at [Slate][], which is just one tool to help you document your API. It might not be to everyone’s taste, but it provides a quickstart for anyone who wishes to create HTML-based documentation and write in Markdown.

在本文中，我们介绍了[Slate][] ，它只是一种可帮助您记录API的工具。 它可能不符合每个人的喜好，但是它为希望创建基于HTML的文档并用Markdown编写的任何人提供了快速入门。

How do you write your API documentation? Let me know in the comments.

您如何编写API文档？ 在评论中让我知道。

> 翻译自: [https://www.sitepoint.com/writing-api-documentation-slate/][https_www.sitepoint.com_writing-api-documentation-slate]

slate api

[Readme.io]: http://dash.readme.io/
[Doxygen]: http://www.stack.nl/~dimitri/doxygen/
[API Blueprint]: http://apiblueprint.org/
[Swagger]: https://helloreverb.com/developers/swagger
[Slate]: https://github.com/tripit/slate
[API documentation created by Slate_ straight out-of-the-box]: /images/20221123/0a8e928419b1479bb38ff5da420a00c3.png
[Travis]: http://docs.travis-ci.com/api/
[localForage]: http://mozilla.github.io/localForage/
[recroom]: http://mozilla.github.io/recroom/
[jquery.tocify.js]: https://github.com/gfranko/jquery.tocify.js
[documentation]: https://www.ruby-lang.org/en/installation/
[Docker]: https://www.docker.com/
[fork]: https://help.github.com/articles/fork-a-repo/
[The default Slate folder structure]: /images/20221123/d81add03e1c64151be06eb716f0139dd.png
[Rouge]: http://rouge.jayferd.us/demo
[Notices]: https://s3.amazonaws.com/f.cl.ly/items/1F2J1z0m0g0r0211240n/api-docs-notices.png
[this online tool]: http://www.tablesgenerator.com/markdown_tables
[An example Callout]: https://s3.amazonaws.com/f.cl.ly/items/2O2z0R1n0t10183G2q2r/api-docs-callout.png
[on the wiki]: https://github.com/tripit/slate/wiki/Markdown-Syntax
[Github Pages]: https://pages.github.com/
[Middleman Github Pages]: https://github.com/neo/middleman-gh-pages
[in Github_s documentation]: https://help.github.com/articles/creating-project-pages-manually/
[Slate wiki]: https://github.com/tripit/slate/wiki/Deploying-Slate
[relevant documentation]: https://help.github.com/articles/setting-up-a-custom-domain-with-github-pages/
[http_docs.example.com]: http://docs.example.com
[https_www.sitepoint.com_writing-api-documentation-slate]: https://www.sitepoint.com/writing-api-documentation-slate/