时间戳

首页 > 解决方案 > 我可以在 RAML 文档中包含代码示例吗？

raml - 我可以在 RAML 文档中包含代码示例吗？

问题描述

是否可以在 RAML 文件中包含代码片段，例如如何以不同语言使用每个端点的示例？

理想情况下，是这样的：

/account:
  post:
    description: Create an account
    (snippets):
      javascript: |
        fetch('http://my-api/account', {method: 'post', body: ...})
          .then(() => console.log('Success!'));
      php: |
        // whatever the php version of the above is
      golang: |
        // you know what I mean. Also, it'd be nice to get color coding for each language
    body:
      ...

标签： raml

解决方案

也许您需要在“文档”下添加文本。在那里您也可以简单地添加代码片段：

#%RAML 1.0
baseUri:
title: My API
version: v1.0
mediaType: [ application/json ]
protocols: [ HTTP, HTTPS ]
documentation:
  - title: Introduction
    content: |
      This is a sample documentation. This API works like this:

      Please see [Official documentation](https://My-URL) for more information
      about the API.

      ```javascript
      var raml2html = require('raml2html');
      Some examples about how to query the REST API
      // Comments if needed
      ```
  - title: Chapter two
    content: |
      More content here. Including **bold** text!
      Small table:

      | A | B | C |
      |---|---|---|
      | 1 | 2 | 3 |
      Done

types:
  Error:
    type: object
    example: |
      {
        "code": 400,
        "message": "Error occured while parsing Json"
      }
    properties:
      code:
        type: integer
        description: The Error code
        required: true
      message:
        type: string
        description: The Error message
        required: true

推荐阅读