raml

raml

In a recent article I introduced Slate, a static site generator specifically designed for writing API documentation. This time around, I’m going to look at something which in many ways is even better.

在最近的文章中，我介绍了Slate ，这是一个专门用于编写API文档的静态站点生成器。 这次，我将研究在许多方面甚至更好的东西。

But first, if you’ll indulge me for just a moment, I’d like to begin by quoting myself from that article;

但是首先，如果您要让我沉迷片刻，那么我想从那篇文章中引述自己开始；

[an] API is only as good as its documentation

[an] API仅与其文档一样好

I think it’s worth repeating, since it’s all-too-frequently overlooked, and it’s one of the motivations for this short series of articles on some of the tools out there to help you write great documentation.

我认为这是值得重复的，因为它经常被忽略，这是本系列简短文章的动机之一，其中的一些工具可帮助您编写出色的文档。

Slate is a useful tool, but despite the relatively rigid structure of the pages themselves, the actual documentation is pretty freeform.

Slate是一个有用的工具，但是尽管页面本身的结构比较僵硬，但实际的文档还是相当自由的形式。

RAML (RESTful API Modeling Language) provides a structured, unambiguous format for describing a RESTful API. It allows you to describe your API; the endpoints, the HTTP methods to be used for each one, any parameters and their format, what you can expect by way of a response and more.

RAML(RESTful API建模语言)提供了一种结构化，明确的格式来描述RESTful API。 它允许您描述您的API； 端点，用于每个端点的HTTP方法，任何参数及其格式，可以通过响应得到的期望等等。

You can use RAML in a number of ways;

您可以通过多种方式使用RAML。

It can be used in the design and specification stage to describe the API you plan to build

它可以在设计和规范阶段用于描述您计划构建的API You can use RAML to generate documentation

您可以使用RAML生成文档 RAML can be used to implement interactive API consoles

RAML可用于实现交互式API控制台 You can test against RAML

您可以针对RAML进行测试 It be used to generate mock API responses

用于生成模拟API响应

In this article I’ll primarily look at generating documentation; in a later article I’ll look at how you can integrate RAML into your API testing. But first, let’s look at how to write a RAML document.

在本文中，我将主要研究生成文档。 在以后的文章中，我将介绍如何将RAML集成到API测试中。 但是首先，让我们看一下如何编写RAML文档。

写RAML (Writing RAML)

The first thing to note is that RAML is a derivative of YAML. You’ll find it easier to work with RAML if you’ve written YAML before, but if you haven’t then it’s relatively straightforward, or there’s a tutorial here on Sitepoint.

首先要注意的是RAML是YAML的派生。 如果您之前编写过YAML，将会发现使用RAML更加容易，但是如果您还没有这样做，那么它会相对简单一些，或者在Sitepoint上有一个教程 。

Because they’re simply text files, you can of course use any text editor or IDE to create and edit them. However, a better option is to use the Anypoint platform. It provides an API editor, which allows you to edit RAML files with auto-completion, validation as-you-type and an interactive preview of some generated, interactive documentation (we’ll see how to generate that ourselves later).

因为它们只是文本文件，所以您当然可以使用任何文本编辑器或IDE来创建和编辑它们。 但是，更好的选择是使用Anypoint平台。 它提供了一个API编辑器，可让您编辑自动完成的RAML文件，键入时进行验证以及一些生成的交互式文档的交互式预览(我们将在稍后看到如何自行生成)。

To use Anypoint, you’ll first need to sign up – which is free – then add an API, then click “Define an API in API Designer”.

要使用Anypoint，您首先需要注册 (免费)，然后添加API，然后单击“在API Designer中定义API”。

If you’d rather use Sublime, there’s a plugin you can use. It’s available via Package Control; simply do a search for “RAML Syntax Highlighter”.

如果您愿意使用Sublime，则可以使用一个插件 。 通过Package Control可以使用； 只需搜索“ RAML语法突出显示”。

Let’s look at the structure of a RAML file.

让我们看一下RAML文件的结构。

基本信息 (Basic Information)

A RAML file starts with a declaration, indicating the format:

RAML文件以声明开头，指示格式：

#%RAML 0.8

Typically you’d then provide some meta-information about your API, for example:

通常，您通常会提供一些有关API的元信息，例如：

title: My Example API version: v1

title is a required field; version is optional

title是必填字段； version是可选的

You should then provide the Base URI for your API. At its simplest, it can be in the following format:

然后，您应该为API提供基本URI。 最简单地说，可以采用以下格式：

baseUri: http://api.acme.com/

You can also use URI parameters. For example it’s common practice to incorporate a version identifier into API URLs; if you’re taking that approach with yours, you can do this:

您也可以使用URI参数。 例如，通常的做法是将版本标识符合并到API URL中。 如果您采用这种方法，则可以执行以下操作：

baseUri: http://api.acme.com/{version}/

We’ll look at URI parameters in more detail later on, since they become vital when describing resources. But should you need to, you can include additional parameters in your base URI. Amazon’s S3, for example, incorporates the name of the bucket you’re working with into the base URI.

稍后我们将更详细地讨论URI参数，因为它们在描述资源时变得至关重要。 但是，如果需要，您可以在基本URI中包括其他参数。 例如，Amazon的S3将您正在使用的存储桶的名称合并到基本URI中。

You can also indicate whether your API is available over HTTPS by setting the protocols field, for example:

您还可以通过设置protocols字段来指示您的API是否可以通过HTTPS使用，例如：

protocols: [ HTTP, HTTPS ]

You can specify the default media type which your API will return, for example:

您可以指定API将返回的默认媒体类型，例如：

mediaType: application/json

Later when we look at responses, we’ll look at how you can describe multiple response media types, and what to expect from them.

稍后，当我们查看响应时，我们将研究如何描述多种响应媒体类型以及对它们的期望。

You can also incorporate additional documentation – or pages – into your RAML file. For example:

您还可以将其他文档(或页面)合并到RAML文件中。 例如：

documentation - title: Home content: | This example documentation forms part of a tutorial for a [Sitepoint](https://www.sitepoint.com/) article.

Notice how you can include Markdown in your meta-information.

请注意，如何将Markdown包含在元信息中。

There are some other things you can include here, such as how security is implemented, as well as defining traits. We’ll look at these concepts a little later.

您可以在此处包含其他一些内容，例如如何实现安全性以及定义特征 。 我们稍后再讨论这些概念。

That’s much of the basic information covered, so now let’s move onto resources.

这涵盖了很多基本信息，所以现在让我们进入资源。

描述资源 (Describing Resources)

Continuing at the top level of your RAML file, the next step is to outline the available resources. Here’s an example:

从RAML文件的顶层继续，下一步是概述可用资源。 这是一个例子：

/albums: displayName: Album /artists: displayName: Artist

The displayName property is optional, but can help describe what the resources represent “in real life”.

displayName属性是可选的，但可以帮助描述资源在“现实生活中”所代表的含义。

Here we’ve defined two top-level resources, (musical) albums and resources. What we haven’t yet done is described the HTTP methods which can be used to interact with them, but first let’s drill down a little and look at resource URIs and sub-resources.

在这里，我们定义了两个顶级资源，(音乐)专辑和资源。 我们还没有描述可以与之交互的HTTP方法，但首先让我们深入研究一下资源URI和子资源。

Let’s suppose specific albums are represented by their ISRC (International Standard Recording Code); so let’s expand our /albums resource to describe this:

假设特定专辑以其ISRC(国际标准记录代码)表示； 因此，让我们扩展/albums资源来描述这一点：

/albums: /{isrc}: uriParameters: isrc: description: The International Standard Recording Code which uniquely identifies this album type: string pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$

As you can see, URI parameters are denoted by curly brackets. The uriParameters property can be used to provide additional information about these parameters, both meta-information (in this case, a description) as well as a concrete definition of their format – in this example, the data type and a regular expression which defines the specific format.

如您所见，URI参数用大括号表示。 uriParameters属性可用于提供有关这些参数的附加信息，包括元信息(在本例中为description )以及其格式的具体定义-在此示例中，数据类型和正则表达式定义了具体格式。

Using nesting, we can describe sub-resources. For example, suppose we provide an endpoint to retrieve an individual album’s tracklisting:

使用嵌套，我们可以描述子资源。 例如，假设我们提供了一个端点来检索单个专辑的曲目列表：

/albums: /{isrc}: uriParameters: isrc: description: The International Standard Recording Code which uniquely identifies this album type: string pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$ /tracks: displayName: Tracklisting

You can have as much nesting of resources as you wish; just use YAML-style indentation.

您可以根据需要嵌套尽可能多的资源。 只需使用YAML样式的缩进即可。

Now let’s move onto defining the methods one can use on these resources.

现在，让我们继续定义可以在这些资源上使用的方法。

HTTP方法 (HTTP Methods)

Most REST_ful_ APIs tend to implement the four most common HTTP methods; GET for retrieval, PUT for updates, POST for creation and DELETE for, well, deleting resources. Our example API is no different. So, let’s modify our albums resource to reflect this:

大多数REST_ful_ API倾向于实现四种最常见的HTTP方法。 GET用于检索，PUT用于更新，POST用于创建，DELETE用于删除资源。 我们的示例API没什么不同。 因此，让我们修改相册资源以反映这一点：

/albums: get: description: Retrieve a list of albums post: description: Create a new album /{isrc}: uriParameters: isrc: description: The International Standard Recording Code which uniquely identifies this album type: string pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$ get: description: Retrieve the specified album put: description: Update an album delete: description: Delete this album

Here we’re indicating that a GET request to /albums will retrieve a list of albums, and a POST to the same URI is used to create one. Drilling-down, a GET request to /albums/{isrc} will retrieve information about a specific album, specified using the URI parameter isrc. a PUT request is used to update the album, a DELETE request to delete it.

在这里，我们指示对/albums的GET请求将检索/albums列表，并使用对相同URI的POST创建一个相册。 向下钻取，对/albums/{isrc}的GET请求将检索有关使用URI参数isrc指定的特定专辑的信息。 PUT请求用于更新相册， DELETE请求用于删除相册。

描述回应 (Describing Responses)

Now that we’ve defined our resources and the available methods, we need to be able to describe the responses a user can expect.

现在我们已经定义了资源和可用的方法，我们需要能够描述用户可以期望的响应。

In order to demonstrate this, we’ll provide some additional detail about specific albums.

为了证明这一点，我们将提供有关特定专辑的其他一些详细信息。

In order to describe responses, we need to drill down a few more levels. First, we need to describe the possible response codes, and thereafter we need to break down responses into their components – typically, the response body – and then the possible response media types. Here’s an example to make that a little clearer:

为了描述响应，我们需要进一步挖掘一些级别。 首先，我们需要描述可能的响应代码，然后我们需要将响应分解为它们的组成部分(通常是响应主体)，然后是可能的响应媒体类型。 这是一个使这一点更清楚的示例：

/albums: /{isrc}: get: description: Retrieve the specified album responses: 200: body: application/json: schema: | { "$schema": "http://json-schema.org/schema", "type": "object", "description": "An album", "properties": { "title": { "type": "string" }, "artist": { "type": "string" }, "label": { "type": "string" }, "year": { "type": "integer" } }, "required": [ "title", "artist" ] } example: | { "title": "Dubnobasswithmyheadman", "artist": "Underworld", "label": "Junior Boy's Own", "year": 1994 }

Here we’re demonstrating a successful response – i.e., one with an HTTP response code of 200. What we’re interested in specifically is the response body, although you can also define any response headers here too. We then drill down into the available response types; in this case, we’re just representing JSON – though you’re free to define multiple response types if your API supports them.

这里我们展示了一个成功的响应，即HTTP响应代码为200的响应。我们特别感兴趣的是响应正文，尽管您也可以在此处定义任何响应标头。 然后，我们深入研究可用的响应类型； 在这种情况下，我们仅代表JSON-尽管如果您的API支持它们，您可以自由定义多种响应类型。

Once we get down to a successful response’s body, we specify two properties; schema and example.

确定成功响应的主体后，我们将指定两个属性： schema和example 。

The schema property contains a JSON schema which defines the structure of the expected JSON. I’ll be covering JSON schema in another article very soon. The example property contains just that, making it clear what sort of response someone calling your API can expect.

schema属性包含一个JSON模式 ，该模式定义了所需JSON的结构。 我很快将在另一篇文章中介绍JSON模式。 example属性仅包含该内容，从而使调用您的API的人可以期望得到哪种响应。

查询参数 (Query Parameters)

We can define query parameters (typically for GET requests) in a very similar manner in which we defined URI parameters.

我们可以以与定义URI参数非常相似的方式定义查询参数(通常用于GET请求)。

To illustrate, let’s look again at our /albums endpoint, supposing that we wanted to implement pagination; so, we probably want to provide a query parameter named page which allows the requesting party to specify which page they want to retrieve.

为了说明，让我们再次看一下/albums端点，假设我们想实现分页。 因此，我们可能希望提供一个名为page的查询参数，该参数允许请求方指定他们要检索的页面。

Here’s how we might do that:

我们可以这样做：

/albums: get: description: Retrieve a list of albums queryParameters: page: description: Specify the page that you want to retrieve type: integer example: 1

Again, the definition of the query parameter is a mixture of meta-information – such as the description and an example – and some properties which help explicitly define what the API expects; here we’re making it clear that the page parameter should be an integer.

同样，查询参数的定义是元信息(例如description和example )以及一些有助于显式定义API期望的属性的混合体。 在这里，我们明确指出page参数应该是整数。

索取资料 (Request Data)

Let’s revisit our “Create an album” endpoint, which you’ll recall involves making a POST request to the /albums URI.

让我们重新访问“创建专辑”端点，您会记得其中涉及到对/albums URI的POST请求。

We can expand upon this by describing the data someone is required to include, the mechanism used to provide it, and some specifics about the various fields.

我们可以通过描述要求某人包括的数据，用于提供数据的机制以及有关各个字段的一些细节来扩展此范围。

Here’s an example:

这是一个例子：

/albums: get: description: Retrieve a list of albums post: description: Create a new album body: application/x-www-form-urlencoded: formParameters: isrc: description: The International Standard Recording Code which uniquely identifies this album type: string pattern: ^[a-zA-Z]{2}\-[0-9a-zA-Z]{3}\-\d{2}\-\d{5}$ required: true name: description: The name of the album type: string required: true artist: description: The name of the artist type: string required: true label: description: The label it was released under type: string required: false year: description: The year the album was released type: integer required: false minimum: 1900 maximum: 3000

Here we’re defining the expected request body when POSTing to this endpoint. We’re indicating that the request should be of type application/x-www-form-urlencoded.

在这里，我们定义了发布到此端点时的预期请求正文。 我们指示该请求应为application/x-www-form-urlencoded 。

Next, we break down the expected request body into parameters with the formParameters property. Then we list the possible fields, provide some meta-data about each one, as well as the expected type. We can also indicate which fields are required and which are optional, as well as some validation rules – in this case we use a regular expression to dictate the format of the ISRC, and some relatively sensible boundaries for the year of release.

接下来，我们使用formParameters属性将期望的请求主体分解为参数。 然后，我们列出可能的字段，并提供有关每个字段的一些元数据以及预期的类型。 我们还可以指出哪些字段是必填字段，哪些是可选字段，以及一些验证规则-在这种情况下，我们使用正则表达式来指定ISRC的格式以及发行年份的一些相对合理的界限。

安全 (Security)

Chances are your API is secured in some way – be it using OAuth, access tokens or simply just HTTP Basic Authentication.

您的API可能会以某种方式得到保护-使用OAuth，访问令牌还是仅使用HTTP基本身份验证即可。

In RAML you can define your security schemes towards the top of your file, alongside the basic information. You’ll find some examples in the specification document, but as an example let’s look at OAuth2. Here’s what the security scheme definition might look like:

在RAML中，您可以在文件顶部以及基本信息旁边定义安全方案。 您可以在规范文档中找到一些示例，但作为示例，让我们看一下OAuth2。 安全方案定义如下所示：

securitySchemes: - oauth_2_0: description: | Acme uses OAuth2 to authenticate most requests type: OAuth 2.0 describedBy: headers: Authorization: description: | Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter. type: string queryParameters: access_token: description: | Used to send a valid OAuth 2 access token. Do not use together with the "Authorization" header type: string responses: 400: description: | Bad OAuth request (e.g. wrong consumer key, bad nonce, expired timestamp, etc.) 401: description: | Bad or expired token. To fix it, re-authenticate the user. settings: authorizationUri: https://acme.com/oauth/authorize accessTokenUri: https://acme.com/oauth/token authorizationGrants: [ code, token ]

If you look through this, you’ll see it provides a number of key pieces of information;

如果仔细研究，您会发现它提供了许多关键信息。

The type indicates that we’re implementing OAuth 2.0

type表明我们正在实现OAuth 2.0

To authenticate, the API in question expects either an Authorization header or an access_token query parameter

要进行身份验证，有问题的API需要使用 Authorization标头或 access_token查询参数

It lists the possible responses, what they mean and how to fix them

它列出了可能的响应，它们的含义以及解决方法

The settings are specific to OAuth but nonetheless vital; it tells users how to authorize, where to obtain an access token and the OAuth grant types this API supports.

这些settings特定于OAuth，但至关重要。 它告诉用户如何授权，从何处获取访问令牌以及该API支持的OAuth授予类型。

However, this simply defines the security schemes; we still need to indicate that this is what we’re using to secure our API.

但是，这仅定义了安全性方案。 我们仍然需要指出这就是我们用来保护API的方式。

One way is to add the following towards the top of your RAML file:

一种方法是在RAML文件的顶部添加以下内容：

securedBy: [oauth_2_0]

Note that oauth_2_0 matches the element immediately beneath securitySchemes

请注意， oauth_2_0与securitySchemes下方的元素匹配

Some APIs, however, make some endpoints publicly available, but others may be protected. You can define the security approach on a per-endpoint basis, for example:

但是，某些API使某些端点公开可用，但其他端点可能受到保护。 您可以基于每个端点定义安全性方法，例如：

/albums: get: securedBy: [null, oauth_2_0] post: securedBy: [oauth_2_0]

Here we’re indicating that authentication is optional for retrieving a list of albums, but that a user must be authenticated in order to create one.

在这里，我们表示身份验证对于检索相册列表是可选的，但是必须对用户进行身份验证才能创建专辑。

特质 (Traits)

You’ll probably have certain behaviors, policies or characteristics which are common across different endpoints. A good example is pagination; various collections which support pagination will no doubt use the same approach, to keep the API consistent. Or, as we’ve seen in the Security section, you may have different degrees of security, such as public or “authorization required”.

您可能会有某些行为，策略或特征，这些行为，策略或特征在不同端点之间是相同的。 分页就是一个很好的例子。 支持分页的各种集合无疑将使用相同的方法来保持API的一致性。 或者，正如我们在“安全性”部分所看到的，您可能具有不同程度的安全性，例如公共或“需要授权”。

Rather than repeat the same configuration across multiple endpoints, you can define traits. By-and-large, the concept is synonymous with traits in PHP.

您可以定义trait ，而不是在多个端点上重复相同的配置。 总的来说，该概念与PHP中的特征同义。

Here’s a simple example of creating a trait to indicate that the results from a given endpoint support simple pagination:

这是一个创建特征以指示给定端点的结果支持简单分页的简单示例：

traits: - paged: queryParameters: page: description: Specify the page that you want to retrieve type: integer required: true example: 1

Now you can apply this to an endpoint using the is property, like so:

现在，您可以使用is属性将其应用于端点，如下所示：

/albums: get: is: [ paged ]

You can also pass in variables. As an example, let’s extend our paged trait to include a number of results per page. We’ll specify a maximum number of results per page, which can be overridden on a per-endpoint basis. Here’s the trait definition:

您也可以传递变量。 例如，让我们扩展paged特征，使其每页包含许多结果。 我们将为每页指定最大结果数，可以在每个端点的基础上对其进行覆盖。 这是特征定义：

traits: - paged: queryParameters: page: description: Specify the page that you want to retrieve type: integer required: true example: 1 perPage: type: integer description: The number of results per page, not to exceed <<maxPerPage>> maximum: <<maxPerPage>>

Notice how we can use the variable <<maxPerPage>> both as a maximum restriction, as well as substituting it into our generated documentation.

请注意，我们如何既可以将变量<<maxPerPage>>用作最大限制，又可以将其替换为生成的文档。

To use this, change the definition of the GET /albums endpoint to the following:

要使用此功能，请将GET /albums端点的定义更改为以下内容：

/albums: get: is: [ paged : { maxPerPage : 50 } ]

You’ll find more examples of traits, along with resource types – which share certain characteristics with traits – in the specification. You’ll also find plenty of other documentation along with examples of some of the more complex scenarios you may need to describe. But let’s move on for now to look at some practical applications of RAML.

在规范中 ，您将找到更多特征的示例，以及与特征共享某些特征的资源类型。 您还将找到大量其他文档，以及可能需要描述的一些更复杂方案的示例。 但是，让我们现在继续看一下RAML的一些实际应用。

实践中的RAML (RAML in Practice)

Now that we’ve looked at how to write a simple RAML to describe our RESTful API, it’s time to look at what we can actually do with it.

既然我们已经研究了如何编写一个简单的RAML来描述我们的RESTful API，那么现在该看看我们可以实际使用它做什么。

生成API文档 (Generating API Documentation)

RAML is a very detailed, unambiguous overview of an API, but it’s not terribly user-friendly for our API’s consumers.

RAML是API的非常详细，明确的概述，但是对于我们的API使用者而言，它并非十分友好。

However because it’s a well-defined, open format, there are tools which can help us use this information in a more user-friendly way. Most notably, there are tools which will take our RAML files and produce HTML-based documentation, ready to be published on the Web.

但是，由于它是定义明确的开放格式，因此有些工具可以帮助我们以更加用户友好的方式使用此信息。 最值得注意的是，有些工具可以获取我们的RAML文件并生成基于HTML的文档，这些文档可随时在Web上发布。

Let’s look at a few.

让我们来看一些。

将RAML转换为HTML (Converting RAML to HTML)

raml2html (raml2html)

The raml2html tool, as the name suggests, can convert your RAML files into HTML documentation.

顾名思义， raml2html工具可以将您的RAML文件转换为HTML文档。

Here’s a screenshot of what it looks like out-of-the-box:

这是开箱即用的屏幕截图：

To use it, first install it via npm:

要使用它，首先通过npm安装它：

npm i -g raml2html

Then, to convert a RAML file to HTML you simply do this:

然后，要将RAML文件转换为HTML，只需执行以下操作：

raml2html api.raml > index.html

The result is a fairly reasonable set of API documentation. It has certain dependencies – such as JQuery and Bootstrap – which it pulls in from a CDN, but of course you can modify the resulting HTML as you see fit. You can create your own templates, if you prefer, and simply specify them via the command-line:

结果是一组相当合理的API文档。 它具有某些依赖项(例如JQuery和Bootstrap)，可以从CDN引入该依赖项，但是当然您可以根据需要修改结果HTML。 如果愿意，可以创建自己的模板，只需通过命令行指定它们即可：

raml2html -t custom-template.handlebars -r custom-resource.handlebars -m custom-item.handlebars -i example.raml -o example.html

There’s also a Grunt plugin and a Gulp plugin to make it even easier to generate documentation.

还有一个Grunt插件和一个Gulp插件 ，可以更轻松地生成文档。

There are certain limitations. Security information doesn’t get copied into the HTML, so if you use OAuth for example, you may need to document that separately yourself.

有一定的局限性。 安全信息不会复制到HTML中，因此，例如，如果您使用OAuth，则可能需要自己单独记录。

php-raml2html (php-raml2html)

There’s also a PHP equivalent called php-raml2html.

还有一个等效PHP，称为php-raml2html 。

Here’s a screenshot of the tool’s output:

这是该工具输出的屏幕截图：

There’s also an online demo, and you’ll find the documentation here.

还有一个在线演示 ，您可以在此处找到文档 。

Personally, I prefer raml2html for two reasons. First, the default output is a little cleaner. Second, it produces static HTML – whereas php-raml2html requires PHP to run – which means it’s perfect for hosting on Github Pages or the like. However, if you’re primarily a PHP developer then you might find this tool easier to customize.

就个人而言，出于两个原因，我更喜欢raml2html。 首先，默认输出要干净一些。 其次，它会生成静态HTML(而php-raml2html需要运行PHP)，这意味着它非常适合在Github Pages等上托管。 但是，如果您主要是PHP开发人员，则可能会发现此工具更易于自定义。

API控制台 (API Console)

You can generate more sophisticated documentation from a RAML file using the API Console web component. The resulting HTML is similar in style to raml2html, but it has a killer feature; it provides a console which allows people to interact with your API from within the documentation. It takes care of building forms for you for any available parameters, validating them according to your definitions, as well as being able to work out how to perform authentication.

您可以使用API Console Web组件从RAML文件生成更复杂的文档。 生成HTML的样式与raml2html相似，但是具有杀手级功能。 它提供了一个控制台，使人们可以从文档中与您的API进行交互。 它负责为您构建任何可用参数的表单，并根据您的定义对它们进行验证，并能够确定如何执行身份验证。

To see it in action, there are demos online for Twitter and Github. If you’ve been using the Anypoint Platform you’ll have seen it already; it’s what’s used to generate the interactive documentation in the right-hand column.

要查看实际效果，可以在Twitter和Github上在线观看演示。 如果您一直在使用Anypoint平台，那么您已经看到了它。 这是用于在右侧列中生成交互式文档的内容。

API Console is implemented using Angular, but you don’t necessarily need any experience with it in order to use it.

API控制台是使用Angular实现的，但使用它不一定需要任何经验。

To get up-and-running quickly, simply follow these steps:

要快速启动并运行，只需执行以下步骤：

Clone the repository: git clone git@github.com:mulesoft/api-console.git

克隆存储库： git clone git@github.com:mulesoft/api-console.git

Copy the dist folder into an empty directory to hold your documentation

将dist文件夹复制到一个空目录中以保存您的文档

Copy your .raml file somewhere in that folder

将.raml文件复制到该文件夹​​中的某个位置

Create an HTML file as follows:

创建一个HTML文件，如下所示：

<head> <link rel="stylesheet" href="dist/styles/app.css" type="text/css" /> </head> <body ng-app="ramlConsoleApp" ng-cloak id="raml-console-unembedded"> <raml-console src="api.raml"></raml-console> <script src="dist/scripts/vendor.js"></script> <script src="dist/scripts/app.js"></script> </body>

Modify the src attribute of the <raml-console> directive to point to the correct file

修改<raml-console>指令的src属性以指向正确的文件

Open the file via a web server of some description; be it Apache, Ngnix or Connect

通过某种描述的Web服务器打开文件； 是Apache，Ngnix还是Connect

That’s all there is to it.

这里的所有都是它的。

You can also embed the API Console in an iframe; refer to the project’s README for details.

您还可以将API控制台嵌入到iframe中； 有关详细信息，请参阅项目的自述文件 。

笔记本电脑 (Notebooks)

API Notebooks are another way to allow people to interact with your API. You can embed runnable examples into your web pages, using RAML to describe the underlying API.

API笔记本是允许人们与您的API交互的另一种方法。 您可以使用RAML来描述基础API，将可运行示例嵌入到网页中。

This is perhaps best illustrated with an example; click here for a demo of using an API notebook to interact with Github’s API.

最好用一个例子来说明。 单击此处以演示如何使用API​​笔记本与Github的API进行交互。

You’ll probably want to start here, as this particular part of the documentation is specific to creating a Notebook which runs off RAML.

您可能要从这里开始 ，因为文档的这一特定部分特定于创建运行RAML的Notebook。

其他工具 (Other Tools)

There are a number of other tools available to work with RAML files. For example;

还有许多其他工具可用于处理RAML文件。 例如;

You can convert RAML to Markdown format using this command-line tool.

您可以使用此命令行工具将RAML转换为Markdown格式。

The RAML to Wiki tool allows you to convert RAML into content suitable for a wiki within Confluence or JIRA.

RAML到Wiki工具允许您将RAML转换为适合Confluence或JIRA中的Wiki的内容。

You’ll find a comprehensive list of tools available for working with RAML on this Projects page.

您可以在此“项目”页面上找到可用于使用RAML的完整工具列表。

建立自己的工具 (Build your Own Tool)

Because it’s an open standard, you’re free to build pretty much anything you think would be useful in order to work with RAML files.

因为它是一个开放标准，所以您可以自由构建几乎任何您认为对处理RAML文件有用的东西。

A good place to start is probably this PHP-based RAML parser. It allows you to convert schemas into a validation object, extract a list of routes and more.

一个很好的起点可能是这个基于PHP的RAML解析器 。 它使您可以将模式转换为验证对象，提取路由列表等等。

There are also parsers available for JavaScript, Java, Python and Ruby.

也有适用于JavaScript ， Java ， Python和Ruby的解析器。

结论 (Conclusion)

In this article I’ve taken a fairly comprehensive look at RAML, the RESTful API Modeling Language. It provides a way of describing a RESTful API in clear, comprehensive and unambiguous terms.

在本文中，我对RESTful API建模语言RAML进行了比较全面的介绍。 它提供了一种以清晰，全面和明确的术语描述RESTful API的方法。

Perhaps the most obvious and arguably most useful use for RAML is for generating documentation. We’ve looked at a few approaches to this, most notably the API Console project, which not only generates HTML-based documentation for you, but provides an interactive console which allows readers to try out your API from within the documentation.

也许RAML最明显也是最有用的用法是用于生成文档。 我们已经研究了几种方法，最著名的是API Console项目，该项目不仅为您生成了基于HTML的文档，而且还提供了一个交互式控制台，使读者可以从文档中试用API。

We’ve also looked at a range of other tools. Being a relatively new standard, expect to see plenty more in the near future.

我们还研究了一系列其他工具。 作为一个相对较新的标准，期望在不久的将来会看到更多。

If you’d like to find out more, I’d encourage you to read through the specification, which you’ll also find on Github.

如果您想了解更多信息，我鼓励您通读规范 ，您也可以在Github上找到它 。

翻译自: https://www.sitepoint.com/raml-restful-api-modeling-language/

raml

相关资源：raml-spec：RAML规格-源码