使用RAML描述API文档信息的一些用法整理

女爷i 2021-11-02 13:00 570阅读 0赞

RAML是Restful API Modeling Language的缩写，是用来描述API信息的文档。

创建一个.raml后缀的文件，用Atom打开。

## 基本用法 ##

#%RAML 0.8
      title: Book API
      baseUri: http://api.book.com/{version}
      version: v1
      /users:
        /authors:
          /{authorname}:
        /books:
          get:
            queryParameters:
              author:
                displayName: Author
                type: string
                description: An author's full name
                example: Mary
                required: false
              publicationYear:
                displayName: Pub Year
                type: number
                description: The year released for the first time
                example: 1984
                required: false
              rating:
                displayName: Rating
                type: number
                description: Average rating
                required: false
              isBn:
                displayName: ISBN
                type: string
                minLength: 10
                example: 0321736079
          put:
            queryParameters:
              access_token:
                displayName: Access Token
                type: string
                description: Token giving you permission to make call
                required: true
          post:
          /{bookTitle}:
            get:
              description: Retrieve a specific book title
              responses:
                200:
                  body:
                    application/json:
                      example: |
                        {
                          "data":{
                            "id": "SbBGk",
                            "title": "its the title",
                            "descritpion": null
                          },
                          "success": true,
                          "status": 200
                        }
    
            put:
            delete:
            /author:
              get:
            /publiser:
              get:

以上，

● 类型/users:看作是resource,也就是以/开始，:结尾，而且resource是嵌套存在的  
● queryParameters描述查询字符串

接下来把.raml转换成html格式，有一个开源的项目。

→ 参考：https://github.com/raml2html/raml2html  
→ 全局安装：npm i -g raml2html  
→ .raml文件所在文件夹内打开命令窗口，输入：raml2html example.raml > example.html

就是这么个效果：

![417212-20160218155139472-1739282833.png][]

## Body Parameters ##

POST请求，通常把参数放到body中传递，在RAML中如何描述呢？

在Body中的参数传递有很多方式，需要在Headers下的Content-Type中设置。Content-Type这个key可能的值包括：multipart/form-data, application/json, application/x-www-form-urlencoded等等。

**1、通过multipart/form-data**

/file-content:
      description: The file to be reproduced by the client
      get:
        description: Get the file content
        responses:
          200:
            body:
              binary/octet-stream:
                example:
                  !include heybulldog.mp3
      post:
        description: |
           Enters the file content for an existing song entity.
    
           Use the "binary/octet-stream" content type to specify the content from any consumer (excepting web-browsers).
           Use the "multipart-form/data" content type to upload a file which content will become the file-content
        body:
          binary/octet-stream:
          multipart/form-data:
            formParameters:
              file:
                description: The file to be uploaded
                required: true
                type: file

以上，

● Content-Type能接受的类型是binary/octet-stream或multipart/form-data  
● 对于multipart/form-data类型，键值数据放在了formParameters中  
● !include heybulldog.mp3表示把heybulldog.mp3文件引入进来

**2、通过JSON Shema**

JSON Shema用来描述JSON格式。

为什么需要JSON Schema呢？

举个例子：

{
        "id":1,
        "name":"a green door",
        "price":12.50,
        "tags":["home", "green"]
    }

我们可能会问：

● 什么是id  
● name字段必须吗  
● price的值可以是0吗  
● tags所代表的数组元素是string类型吗？

JSON Schema就是解决这些问题的。

{
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Product",
        "description": "A product from Acme's catalog",
        "type": "object"
    }

以上，

● $schema表示当前JSON Shema所采用的版本  
● type字段是必须的，是object类型

接着，对id字段约束。

对name字段约束。

对price字段约束。

{
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Product",
        "description": "A product from Acme's catalog",
        "type": "object",
        "properties": {
            "id": {
                "description": "The unique identifier for a product",
                "type": "integer"
            },
            "name": {
                "description": "Name of the product",
                "type": "string"
            },
            "price": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true
            }
        },
        "required": ["id", "name", "price"]
    }

对tags字段约束。

{
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Product",
        "description": "A product from Acme's catalog",
        "type": "object",
        "properties": {
            "id": {
                "description": "The unique identifier for a product",
                "type": "integer"
            },
            "name": {
                "description": "Name of the product",
                "type": "string"
            },
            "price": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true
            },
            "tags": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "minItems": 1,
                "uniqueItems": true
            }
        },
        "required": ["id", "name", "price"]
    }

数组如何用JSON Schema描述呢？

[
        {
            "id": 2,
            "name": "An ice sculpture",
            "price": 12.50,
            "tags": ["cold", "ice"],
            "dimensions": {
                "length": 7.0,
                "width": 12.0,
                "height": 9.5
            },
            "warehouseLocation": {
                "latitude": -78.75,
                "longitude": 20.4
            }
        },
        {
            "id": 3,
            "name": "A blue mouse",
            "price": 25.50,
            "dimensions": {
                "length": 3.1,
                "width": 1.0,
                "height": 1.0
            },
            "warehouseLocation": {
                "latitude": 54.4,
                "longitude": -32.7
            }
        }
    ]

用JSON Shema描述就是这样：

{
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "Product set",
        "type": "array",
        "items": {
            "title": "Product",
            "type": "object",
            "properties": {
                "id": {
                    "description": "The unique identifier for a product",
                    "type": "number"
                },
                "name": {
                    "type": "string"
                },
                "price": {
                    "type": "number",
                    "minimum": 0,
                    "exclusiveMinimum": true
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                },
                "dimensions": {
                    "type": "object",
                    "properties": {
                        "length": {"type": "number"},
                        "width": {"type": "number"},
                        "height": {"type": "number"}
                    },
                    "required": ["length", "width", "height"]
                },
                "warehouseLocation": {
                    "description": "Coordinates of the warehouse with the product",
                    "$ref": "http://json-schema.org/geo"
                }
            },
            "required": ["id", "name", "price"]
        }
    }

RAML也用到了JSON Shema，就像这样：

body:
      application/json:
        schema: |
          {
            "type": "object",
            "$schema": "http://json-schema.org/draft-03/schema",
            "id": "http://jsonschema.net",
            "required": true,
            "properties": {
              "songTitle": {
                "type": "string",
                "required": true
              },
              "albumId": {
                "type": "string",
                "required": true,
                "minLength": 36,
                "maxLength": 36
              }
            }
          }
        example: |
          {
            "songId": "550e8400-e29b-41d4-a716-446655440000",
            "songTitle": "Get Lucky",
            "albumId": "183100e3-0e2b-4404-a716-66104d440550"
          }

## schemas ##

每个资源都有自己的schema,是否可以把所有资源的schema合并到同一个地方呢？

RAML提供了schemas字段。

schemas:
     - song: |
        {
          "type": "object",
          "$schema": "http://json-schema.org/draft-03/schema",
          "id": "http://jsonschema.net",
          "required": true,
          "properties": {
            "songTitle": {
              "type": "string",
              "required": true
            },
            "albumId": {
              "type": "string",
              "required": true,
              "minLength": 36,
              "maxLength": 36
            }
          }
        }

按如下引用：

body:
      application/json:
        schema: song
        example: |
          {
            "songId": "550e8400-e29b-41d4-a716-446655440000",
            "songTitle": "Get Lucky",
            "albumId": "183100e3-0e2b-4404-a716-66104d440550"
          }

## Resource Types资源类型 ##

每个资源通有相似的部分，能否把这些相似的部分提取抽象出来呢？

假设有2个资源：/resources和/\{resourceId\}

#%RAML 0.8
    title:
    
    /resources:
      get:
      post:
      /{resourceId}:
        get:
        put:
        delete:

以上，resource大致可以分成针对集合和针对个体的，所以，在RAML中通过resourceTypes对资源进行分类，有这样的表达方式：

resourceTypes:
      - collection:
          get:
          post:
      - collection-item:
          get:

于是collection类型可以写成这样：

以上，

● <<resourcePathName>>是占位符，类似表示songs  
● 另外<<resourcePath>>是占位符，类似表示/songs  
● <<resourcePathName|!singularize>>是占位符，类似表示song

● <<resourcePathName|!pluralize>>是占位符，类似表示songs

然后这样使用：

/songs:
      type: collection
      get:
        queryParameters:
          songTitle:
            description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
            required: true
            minLength: 3
            type: string
            example: "Get L"
        responses:
          200:
            body:
              application/json:
                example: |
                  "songs": [
                      {
                        "songId": "550e8400-e29b-41d4-a716-446655440000",
                        "songTitle": "Get Lucky"
                      },
                      {
                        "songId": "550e8400-e29b-41d4-a716-446655440111",
                        "songTitle": "Loose yourself to dance"
                      },
                      {
                        "songId": "550e8400-e29b-41d4-a716-446655440222",
                        "songTitle": "Gio sorgio by Moroder"
                      }
                      ]
      post:
        body:
          application/json:
              example: |
                {
                  "songId": "550e8400-e29b-41d4-a716-446655440000",
                  "songTitle": "Get Lucky",
                  "albumId": "183100e3-0e2b-4404-a716-66104d440550"
                }

collection-item类型可以写成这样：

resourceTypes:
      - collection:
      ...
    
      - collection-item:
          description: Entity representing a <<resourcePathName|!singularize>>
          get:
            description: |
              Get the <<resourcePathName|!singularize>>
              with <<resourcePathName|!singularize>>Id =
              {
         <<resourcePathName|!singularize>>Id}
            responses:
              200:
                body:
                  application/json:
              404:
                body:
                  application/json:
                    example: |
                      {
         "message": "<<resourcePathName|!singularize>> not found" }

然后这样使用：

/songs:
      ...
      /{songId}:
        type: collection-item
        get:
          responses:
            200:
              body:
                application/json:
                  example: |
                    {
                      "songId": "550e8400-e29b-41d4-a716-446655440000",
                      "songTitle": "Get Lucky",
                      "duration": "6:07",
                      "artist": {
                        "artistId": "110e8300-e32b-41d4-a716-664400445500"
                        "artistName": "Daft Punk",
                        "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
                      },
                      "album": {
                        "albumId": "183100e3-0e2b-4404-a716-66104d440550",
                        "albumName": "Random Access Memories",
                        "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
                      }
                    }

以上，  
● 在resourceTypes中的谓词get,post等，可以在具体的resource中进行重新定义  
● 在resrouce级别，通过type: collection-item或type: collection与resourceTypes对应

## Parameters ##

以上，resourceTypes字段所代表的是一个对集合和个体类型相同操作的一个封装，在这些操作中，在这些请求响应中，有时需要通过example字段来举例，通常这样写：

example: |
        {
            ...
        }
    
    或者
    
    example: |
    [
        {
        
        },
        {
        
        }
    ]

但在RAML中，为我们提供了<<exampleCollection>>和<<exampleItem>>占位符分别表示集合和个体。

resourceTypes:
      - collection:
          description: Collection of available <<resourcePathName>> in Jukebox.
          get:
            description: Get a list of <<resourcePathName>>.
            responses:
              200:
                body:
                  application/json:
                    example: |
                      <<exampleCollection>>
          post:
            description: |
              Add a new <<resourcePathName|!singularize>> to Jukebox.
            queryParameters:
              access_token:
                description: "The access token provided by the authentication application"
                example: AABBCCDD
                required: true
                type: string
            body:
              application/json:
                schema: <<resourcePathName|!singularize>>
                example: |
                  <<exampleItem>>
            responses:
              200:
                body:
                  application/json:
                    example: |
                      { "message": "The <<resourcePathName|!singularize>> has been properly entered" }
      - collection-item:
          description: Entity representing a <<resourcePathName|!singularize>>
          get:
            description: |
              Get the <<resourcePathName|!singularize>>
              with <<resourcePathName|!singularize>>Id =
              {
         <<resourcePathName|!singularize>>Id}
            responses:
              200:
                body:
                  application/json:
                    example: |
                      <<exampleItem>>
              404:
                body:
                  application/json:
                    example: |
                      {
         "message": "<<resourcePathName|!singularize>> not found" }

在资源resource部分通常这样调用：

/songs:
        type:
            collection:
                exampleCollection: |
                    [
                        ...
                    ]
        /{songId}:
            type:
                collection-item: 
                    exampleItem: |
                    {
                        ...
                    }

具体来说，类似这样：

/songs:
      type:
        collection:
          exampleCollection: |
            [
              {
                "songId": "550e8400-e29b-41d4-a716-446655440000",
                "songTitle": "Get Lucky"
              },
              {
                "songId": "550e8400-e29b-41d4-a716-446655440111",
                "songTitle": "Loose yourself to dance"
              },
              {
                "songId": "550e8400-e29b-41d4-a716-446655440222",
                "songTitle": "Gio sorgio by Morodera"
              }
            ]
          exampleItem: |
            {
              "songId": "550e8400-e29b-41d4-a716-446655440000",
              "songTitle": "Get Lucky",
              "albumId": "183100e3-0e2b-4404-a716-66104d440550"
            }
      get:
        queryParameters:
          songTitle:
            description: "The title of the song to search (it is case insensitive and doesn't need to match the whole title)"
            required: true
            minLength: 3
            type: string
            example: "Get L"
      /{songId}:
        type:
          collection-item:
            exampleItem: |
              {
                "songId": "550e8400-e29b-41d4-a716-446655440000",
                "songTitle": "Get Lucky",
                "duration": "6:07",
                "artist": {
                  "artistId": "110e8300-e32b-41d4-a716-664400445500"
                  "artistName": "Daft Punk",
                  "imageURL": "http://travelhymns.com/wp-content/uploads/2013/06/random-access-memories1.jpg"
                },
                "album": {
                  "albumId": "183100e3-0e2b-4404-a716-66104d440550",
                  "albumName": "Random Access Memories",
                  "imageURL": "http://upload.wikimedia.org/wikipedia/en/a/a7/Random_Access_Memories.jpg"
                }
              }

## Includes ##

可以把一些example放到单独的文件，然后通过!include关键字来引用这些文件。

/songs:
      type:
        collection:
          exampleCollection: !include jukebox-include-songs.sample
          exampleItem: !include jukebox-include-song-new.sample
      /{songId}:
        type:
          collection-item:
            exampleItem: !include jukebox-include-song-retrieve.sample

## traits ##

如何描述查询、排序、分页呢？

traits:
      - searchable:
          queryParameters:
            query:
              description: |
                JSON array [{
         "field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] <<description>>
              example: |
                <<example>>aml
                
      - orderable:
          queryParameters:
            orderBy:
              description: |
                Order by field: <<fieldsList>>
              type: string
              required: false
            order:
              description: Order
              enum: [desc, asc]
              default: desc
              required: false
      - pageable:
          queryParameters:
            offset:
              description: Skip over a number of elements by specifying an offset value for the query
              type: integer
              required: false
              example: 20
              default: 0
            limit:
              description: Limit the number of elements on the response
              type: integer
              required: false
              example: 80
              default: 10

按如下使用这些trait。

/songs:
      type:
        collection:
          exampleCollection: !include jukebox-include-songs.sample
          exampleItem: !include jukebox-include-song-new.sample
      get:
        is: [
              searchable: {description: "with valid searchable fields: songTitle", example: "[\"songTitle\", \"Get L\", \"like\"]"},
              orderable: {fieldsList: "songTitle"},
              pageable
            ]

另外，schema也可以放到单独的文件中，然后通过!include引用。

schemas:
     - song: !include jukebox-include-song.schema
     - artist: !include jukebox-include-artist.schema
     - album: !include jukebox-include-album.schema

resourceTypes也可以放到单独的文件中：

resourceTypes: !include jukebox-includes-resourceTypes.inc

转载于:https://www.cnblogs.com/darrenji/p/5198524.html

[417212-20160218155139472-1739282833.png]: /images/20211101/0d74a705cb5247c0bcf0e58c465cf3c1.png