2

这是我的 api 蓝图文件:

FORMAT: 1A    
# system API

These endpoints are use to get contents from the system crawler


## Get posts [/posts/{?publish_gte,publish_lte,publish_gt,publish_lt,page,page_size}]
### Get posts which crawled [GET]
You should at least fill one of the time based fields
+ Request

    + Headers

            token: token string

+ Parameters

    + `publish_gte` (string, optional) - Search for posts with publish time greater than or equal to this time (ISO8601 format)
    + `publish_lte` (string, optional) - Search for posts with publish time less than or equal to this time (ISO8601 format)
    + `publish_gt` (string, optional) - Search for posts with publish time greater than to this time (ISO8601 format)
    + `publish_lt` (string, optional) - Search for posts with publish time less than to this time (ISO8601 format)
    + page (number, optional) - The page number of the response
    + `page_size` (number, optional) - Size of a page in the response

+ Response 200 (application/json)

    + Attributes

        + message (string, required) - Extra information about the request
        + response (PostsResponse, required, fixed-type) - The details of the posts

+ Response 400 (application/json)

    + Attributes

        + message `empty request` (string, required) - Extra information about the request
        + response (required) - The details of your response

+ Response 401 (application/json)

    + Attributes

        + message (string, required) - Extra information about the request
        + response (required) - The details of your response


# Data Structures

## MainPlatformIdResponse (object)
+ 1234567 (ChannelResponse, fixed-type) - The details of the platform id you request

## MainUsernameResponse (object)
+ abcdefg (ChannelResponse, fixed-type) - The details of the username you request

## PostsResponse (object)
+ `total_count`: 1000 (required) - The count of all posts for this request
+ `response_count`: 1000 (number, required) - The count of posts in this response
+ data (array[DataResponse], required, fixed-type) - The details of the posts

## ChannelsResponse (object)
+ data (array[ChannelDataResponse], required, fixed-type) - The details of the posts

## DataResponse (object)
+ `unique_id`: 123456_123 (string, required, fixed-type) - The id of the post object in sayna DB. It is in the format of CHANNELID_POSTID
+ `platform_id`: 123456 (string, required) - The id of the post in system
+ url: https://t.me/akharinkhabar/1234 (string, required) - The post url in the platform
+ date: `2019-05-29T18:45:35` (string, required) - The date of the post in system (ISO8601 format)
+ `first_fetch_time`: `2019-05-29T18:45:35` (string, required) - The first time which this post fetched (ISO8601 format)
+ `publish_time`: `2019-05-29T18:45:35` (string, required) - The time in which we give the post in the api request (ISO8601 format)
+ visit: 1234 (number, required) - The number of visits of this post in system
+ deleted: false (boolean, required) - Shows that wehter the post deleted
+ content (ContentResponse, required) - The content of the post
+ channel (ChannelResponse, required) - The channel details of this post

## ChannelDataResponse
+ `platform_ids` (MainPlatformIdResponse, required, fixed-type) - Details of the channels for the platform_ids request
+ usernames (MainUsernameResponse, required, fixed-type) - Details of the channels for the usernames request

## ChannelResponse (object)
+ `platform_id`: 1234567 (string, required) -The id of the channel in the system
+ username: abcd (string, required) - The username of the channel
+ priority: 2 (number, required) - The priority of the channel in The Sayna system
+ url: https://t.me/abcd (string, required) - The url of the channel in the system
+ title: abcd channel (string, required) - The title of the channel
+ description: abcd channel description (string, required) - Channel bio
+ members: 12345 (number, required) - The number of members of the channel
+ `profile_photo` (ProfilePhotoResponse, required, fixed-type) - The details of the profile image. If the channel has no profile photo (when we fetch its infos) we give an empty object

## ContentResponse (object)
+ md: __content__ (string, required) - The content of the post in Markdown format. We, also, put the poll question in this field if the post is a poll
+ `raw_text`: content (string, required) - The content of the post without any format. We, also, put the poll question in this field if the post is a poll
+ `processed_text`: content (string, required) - The content of the post after some processes. We, also, put the poll question in this field if the post is a poll
+ media (array[MediaResponse], required, fixed-type) - The details of the media of the post
+ entities (array[EntitiesResponse], required, fixed-type) - The details of the post entities

## MediaResponse
+ completed: true (boolean, required) - Is the media completed (download, process and upload)
+ `is_supported`: true (boolean, required) - Is the media supported or not. If the media is not supported we have no download link and no metadata
+ `cdn_url`: `http://cdn-s1.newsbx.com/works/system/2019_05_13/2019_05_13__1006276674_28226_28226.mp4` (string, required) - The url of the media on the CDNs
+ `backup_url`: `http://systemmedia.systmngr.ir/works/system/2019_05_13/2019_05_13__1006276674_28226_28226.mp4` (string, required) - The url of the media on the CDNs
+ type: photo (enum[string], required) - The type of the media of the post
    + Members
        + photo
        + sticker
        + video
        + round_video
        + gif
        + voice
        + file

+ ext: jpg (string, required) - The extention of the media
+ metadata (MetadataResponse, required) - The meta details about the media

## ProfilePhotoResponse
+ completed: true (boolean, required) - Is the profile photo completed (download, process and upload)
+ `cdn_url`: `http://cdn-s1.newsbx.com/works/system/2019_05_13/2019_05_13__1006276674_28226_28226.mp4` (string, required) - The url of the profile photo on the CDNs
+ `backup_url`: `http://systemmedia.systmngr.ir/works/system/2019_05_13/2019_05_13__1006276674_28226_28226.mp4` (string, required) - The url of the profile photo on the CDNs
+ ext: jpg (string, required) - The extention of the profile photo
+ metadata (ProfilePhotoMetadataResponse, required) - The meta details about the profile photo

## LoginResponse
+ session (SessionResponse, required) - The details of your session
+ user (UserResponse, required) - The details of your user

## SessionResponse
+ `creation_time`: `2019-05-29T18:45:35` (string, required) - The time which your session created
+ `expiration_time`: `2019-05-29T18:45:35` (string, required) - The time which your session will be expired
+ token: 12345678-1234-1234-1234-123456789012 (string, required) - The token with wich you can send requests

## UserResponse
+ active: true (boolean, required) - Is the user active or not
+ username: abcdefgh (string, required) - The username of your account
+ `include_or_exclude`: include (string, required) - Include actions field or exclude them
+ actions (array[ActionResponse], required, fixed-type) - The actions based on include or exclude you can do or cannot do

## ActionResponse
+ work: system (string, required) - The work name which this action belongs to
+ endpoint: posts (string, required) - The endpoint on which the action is defined
+ method: post - The method on which the action of the endpoint is defined

## MetadataResponse
+ size: 2456 (number, required) - The size of the media in bytes
+ width: 800 (number, required) - The width of media if it is a visible media in pixels
+ height: 600 (number, required) - The height of media if it is a visible media in pixels
+ duration: 123 (number, optional) - The duration of the media if it is a video in seconds

## ProfilePhotoMetadataResponse
+ size: 2456 (number, required) - The size of the profile photo in bytes
+ width: 800 (number, required) - The width of the profile photo in pixels
+ height: 600 (number, required) - The height of the profile photo in pixels

## PollResponse (fixed-type)
+ question (string, required) - The poll question
+ type: `anonymous poll` (enum[string], required) - The poll type
    + Members
        + `anonymous poll`
        + `public poll`
+ options (array[PollOptionResponse], required) - The poll options

## XResponse (fixed-type)
+ question (string, required) - The poll question
+ type: `anonymous poll` (enum[string], required) - The poll type
    + Members
        + `anonymous poll`
        + `public poll`
+ options (array[PollOptionResponse], required) - The poll options

## PollOptionResponse
+ index: 1 (number, required) - The option number
+ text (string, required) - The option value
+ percent (number, required) - The option percentage

## EntitiesResponse (fixed-type)
+ One of
    + PollResponse (fixed-type)
    + XResponse (fixed-type)

当我在养蜂场网站生成它时,该entities字段的结果是错误的。我想要一个数组,该数组中的每个项目都可以是PollResponseor之一XResponse是养蜂场生成的。这是使用 aglio 的 json 模式的输出:

"entities": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {},
                      "oneOf": [
                        {
                          "properties": {
                            "PollResponse": {
                              "type": "string"
                            }
                          }
                        },
                        {
                          "properties": {
                            "XResponse": {
                              "type": "string"
                            }
                          }
                        }
                      ],
                      "additionalProperties": false
                    },
                    "description": "The details of the post entities"
                  }
                }
4

1 回答 1

3

此特定示例中的One Of语法是放置文字字符串PollResponse,并且XResponse在 One Of 中,您可以使用它Include来指定要包含特定引用。

## EntitiesResponse (object)
+ One Of
    + Include PollResponse (fixed-type)
    + Include XResponse (fixed-type)

Attributes Kit 中有一个 bug,它是 Apiary 用来渲染属性表的组件。以这种方式使用引用时会发生该错误,我之前已将其报告为https://github.com/apiaryio/attributes-kit/issues/487

如果您查看解析器生成的 JSON Schema(并在 Apiary 中呈现),我相信您的意图是正确的(如果您认为它是错误的,问题跟踪器http://github.com/apiaryio/drafter/issues可用于跟踪 JSON Schema 生成中的错误):

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "response": {
      "type": "object",
      "properties": {
        "total_count": {
          "type": "string"
        },
        "response_count": {
          "type": "number"
        },
        "data": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "unique_id": {
                    "type": "string"
                  },
                  "platform_id": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "date": {
                    "type": "string"
                  },
                  "first_fetch_time": {
                    "type": "string"
                  },
                  "publish_time": {
                    "type": "string"
                  },
                  "visit": {
                    "type": "number"
                  },
                  "deleted": {
                    "type": "boolean"
                  },
                  "content": {
                    "type": "object",
                    "properties": {
                      "md": {
                        "type": "string"
                      },
                      "raw_text": {
                        "type": "string"
                      },
                      "processed_text": {
                        "type": "string"
                      },
                      "media": {
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "completed": {
                                  "type": "boolean"
                                },
                                "is_supported": {
                                  "type": "boolean"
                                },
                                "cdn_url": {
                                  "type": "string"
                                },
                                "backup_url": {
                                  "type": "string"
                                },
                                "type": {
                                  "enum": [
                                    "photo",
                                    "sticker",
                                    "video",
                                    "round_video",
                                    "gif",
                                    "voice",
                                    "file"
                                  ]
                                },
                                "ext": {
                                  "type": "string"
                                },
                                "metadata": {
                                  "type": "object",
                                  "properties": {
                                    "size": {
                                      "type": "number"
                                    },
                                    "width": {
                                      "type": "number"
                                    },
                                    "height": {
                                      "type": "number"
                                    },
                                    "duration": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "size",
                                    "width",
                                    "height"
                                  ]
                                }
                              },
                              "required": [
                                "completed",
                                "is_supported",
                                "cdn_url",
                                "backup_url",
                                "type",
                                "ext",
                                "metadata"
                              ]
                            }
                          ]
                        }
                      },
                      "entities": {
                        "type": "array",
                        "items": {
                          "anyOf": [
                            {
                              "type": "object",
                              "allOf": [
                                {
                                  "oneOf": [
                                    {
                                      "properties": {
                                        "question": {
                                          "type": "string"
                                        },
                                        "type": {
                                          "enum": [
                                            "anonymous poll",
                                            "public poll"
                                          ]
                                        },
                                        "options": {
                                          "type": "array"
                                        }
                                      },
                                      "required": [
                                        "question",
                                        "type",
                                        "options"
                                      ]
                                    },
                                    {
                                      "properties": {
                                        "question": {
                                          "type": "string"
                                        },
                                        "type": {
                                          "enum": [
                                            "anonymous poll",
                                            "public poll"
                                          ]
                                        },
                                        "options": {
                                          "type": "array"
                                        }
                                      },
                                      "required": [
                                        "question",
                                        "type",
                                        "options"
                                      ]
                                    }
                                  ]
                                }
                              ]
                            }
                          ]
                        }
                      }
                    },
                    "required": [
                      "md",
                      "raw_text",
                      "processed_text",
                      "media",
                      "entities"
                    ]
                  },
                  "channel": {
                    "type": "object",
                    "properties": {
                      "platform_id": {
                        "type": "string"
                      },
                      "username": {
                        "type": "string"
                      },
                      "priority": {
                        "type": "number"
                      },
                      "url": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "members": {
                        "type": "number"
                      },
                      "profile_photo": {
                        "type": "object",
                        "properties": {
                          "completed": {
                            "type": "boolean"
                          },
                          "cdn_url": {
                            "type": "string"
                          },
                          "backup_url": {
                            "type": "string"
                          },
                          "ext": {
                            "type": "string"
                          },
                          "metadata": {
                            "type": "object",
                            "properties": {
                              "size": {
                                "type": "number"
                              },
                              "width": {
                                "type": "number"
                              },
                              "height": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "size",
                              "width",
                              "height"
                            ]
                          }
                        },
                        "required": [
                          "completed",
                          "cdn_url",
                          "backup_url",
                          "ext",
                          "metadata"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "platform_id",
                      "username",
                      "priority",
                      "url",
                      "title",
                      "description",
                      "members",
                      "profile_photo"
                    ]
                  }
                },
                "required": [
                  "unique_id",
                  "platform_id",
                  "url",
                  "date",
                  "first_fetch_time",
                  "publish_time",
                  "visit",
                  "deleted",
                  "content",
                  "channel"
                ]
              }
            ]
          }
        }
      },
      "required": [
        "total_count",
        "response_count",
        "data"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "message",
    "response"
  ]
}

我会注意到 Aglio 使用的是更旧版本的 API 蓝图解析器,因此会产生非常不同的 JSON 模式。

于 2019-06-16T12:39:16.963 回答