Emad Helmi
Reputation: 695
api-blueprint does not show nested "One of" attributes correctly
This is my api blueprint file:
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)
When I generate it in the apiary site, the result of the entities field is wrong. I want to have an array that each item in that array could be one of PollResponse or XResponse. Here is what apiary generates. And this is the output of the json schema using the aglio:
"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"
}
}
Upvotes: 2
Views: 794
Answers (1)
kylef
Reputation: 1066
The One Of syntax in this particular example is placing the literal strings PollResponse and XResponse in the One Of, you can use Include to specify that you want to include the particular reference.
## EntitiesResponse (object)
+ One Of
+ Include PollResponse (fixed-type)
+ Include XResponse (fixed-type)
There is a bug in Attributes Kit, which is the component Apiary uses to render the attributes table. The bug happens when using references in this way, I've reported this before as https://github.com/apiaryio/attributes-kit/issues/487.
If you look at the JSON Schema generated by the parser (and presented in Apiary), I believe it is correct from your intention (if you believe it is wrong, the issue tracker http://github.com/apiaryio/drafter/issues can be used to track bugs in the JSON Schema generation):
{
"$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"
]
}
I would note that Aglio is using a much older version of the API Blueprint parser and thus produces very different JSON Schemas.
Upvotes: 3
Related Questions
- Json Schema Not working for nested Attributes
- API Blueprint: Semantic Issue "no value(s) specified"
- JSONSchema - Element can appear alone or within a group
- Adding root to API blueprint when using data structures
- How To Show Nested Attribute Definition In Apiary.io
- Nested array with object in MSON is empty in Apiary.io documentation
- MSON to describe object attributes in blueprint
- How do you specify request body attributes in Apiary.io / API Blueprint?
- API Blueprint resource definition not working correctly
- How to add value description with API Blueprint?