这是我的 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 whether 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 info) 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 extension 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 extension 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 which 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)
当我在 apiary 站点中生成它时，entities 字段的结果是错误的。我想要一个数组，该数组中的每个项目都可以是 PollResponse 或 XResponse 之一。 Here 是养蜂场生成的。这是使用 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"
}
}
最佳答案
此特定示例中的 One Of 语法是将文字字符串 PollResponse 和 XResponse 放在 One Of 中，您可以使用 包含以指定您要包含特定的引用。
## EntitiesResponse (object)
+ One Of
+ Include PollResponse (fixed-type)
+ Include XResponse (fixed-type)
Attributes Kit 中存在一个错误，该组件是 Apiary 用于呈现属性表的组件。以这种方式使用引用时会发生错误，我之前已将此报告为 https://github.com/apiaryio/attributes-kit/issues/487 .
如果您查看解析器生成的 JSON 模式(并在 Apiary 中呈现)，我相信您的意图是正确的(如果您认为这是错误的，问题跟踪器 http://github.com/apiaryio/drafter/issues 可用于跟踪JSON 模式生成):
{
"$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 模式。
关于jsonschema - api-blueprint 未正确显示嵌套 "One of"属性，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/56618534/