docs: add descriptions/examples for hub-rest-api #272
Conversation
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Co-Authored-By: Team Neynar <[email protected]>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
⚙️ Control Options:
|
There was a problem hiding this comment.
PR Review Summary for neynarxyz/OAS Pull Request #272 for fun via copilot
Files Changed
src/hub-rest-api/spec.yaml
Key Changes in src/hub-rest-api/spec.yaml
-
Parameter Descriptions:
- Updated descriptions for parameters such as
dbstats,fid,hash, andurlto provide more detailed information. - Added examples for parameters to illustrate valid values.
- Updated descriptions for parameters such as
-
Response Descriptions:
- Enhanced descriptions for response fields like
nextPageTokento explain their usage and format. - Added examples for response fields and parameters to clarify expected data formats.
- Enhanced descriptions for response fields like
-
Component Schema Updates:
- Improved descriptions for various components, including
CastId,CastHash,FrameActionBody, andLinkBody. - Added examples for component properties to demonstrate valid values.
- Improved descriptions for various components, including
-
Message Data Changes:
- Added detailed descriptions for message data types like
MessageDataCastAdd,MessageDataCastRemove,MessageDataReaction, andMessageDataUserDataAdd. - Provided examples for message properties to illustrate valid data formats.
- Added detailed descriptions for message data types like
-
Overall Improvements:
- The changes improve clarity and usability of the API documentation.
- The enhancements provide better guidance for API consumers, including detailed descriptions and examples.
Review Notes
- The changes are primarily focused on improving the documentation by providing clearer descriptions and examples.
- No functional code changes have been made, indicating that this PR is purely for documentation improvement.
These updates enhance the developer experience by making the API documentation more comprehensive and easier to understand. The added examples and detailed descriptions will help users implement and use the API more effectively.
There was a problem hiding this comment.
General Feedback:
- If the description is already present in the schema, do not add a description where the schema is used, unless there is something specific that differs (for example,
fidandtargetFidcan have the same schema but may have different meanings depending on where they are used). - The
nextPageTokenshould be centralized.
| - name: url | ||
| in: query | ||
| description: "The URL associated with the parent cast. This can be used as an alternative to the FID+hash combination for identifying a parent cast. Supports both standard HTTP(S) URLs (e.g., Warpcast conversation URLs) and chain URLs (e.g., NFT references). The URL must match exactly with the URL stored in the parent cast. Not required if using FID+hash lookup." |
There was a problem hiding this comment.
URL description is not correct
| example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2 | ||
| format: uri | ||
| examples: | ||
| - "https://warpcast.com/~/conversations/0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" # Warpcast conversation URL |
There was a problem hiding this comment.
This example won't work with the API
src/hub-rest-api/spec.yaml
Outdated
| @@ -230,13 +259,18 @@ paths: | |||
| type: object | |||
| properties: | |||
| messages: | |||
| description: "An array of reply casts to the specified parent cast, ordered by recency (newest first). Each cast includes its content, timestamp, and other metadata." | |||
There was a problem hiding this comment.
It's not the newest first but the other way around
src/hub-rest-api/spec.yaml
Outdated
| examples: | ||
| - 616 # Example creator FID | ||
| - 1337 # Another creator FID | ||
| - 42069 # Popular creator FID |
There was a problem hiding this comment.
This should be 3, since Dan is the high quality user
src/hub-rest-api/spec.yaml
Outdated
| @@ -336,9 +377,13 @@ paths: | |||
| items: | |||
| $ref: "#/components/schemas/Reaction" | |||
| nextPageToken: | |||
| description: "Base64-encoded pagination token for fetching the next page of results. An empty value indicates there are no more pages to return. Used in conjunction with the pageSize parameter to implement pagination across large result sets." | |||
There was a problem hiding this comment.
nextPageToken should be a Schema and it should be referenced everywhere else instead of defining it in every single response
| externalDocs: | ||
| description: "Fetch reactions by a target URL" | ||
| url: https://docs.neynar.com/reference/fetch-reactions-by-target | ||
| operationId: fetch-reactions-by-target | ||
| parameters: | ||
| - name: url | ||
| in: query | ||
| description: The URL of the parent cast | ||
| description: "The target URL to fetch reactions for. Can be a regular HTTP(S) URL or a chain URL (e.g., for NFTs). The URL must match exactly with the URL in the original reaction." |
There was a problem hiding this comment.
It can't be a http URL
| - name: reaction_type | ||
| in: query | ||
| description: The type of reaction, either as a numerical enum value or string representation | ||
| description: "The specific type of reaction to filter by. Can be either a like (showing appreciation) or recast (sharing to user's audience). This parameter helps narrow down the reaction results to a specific interaction type." |
There was a problem hiding this comment.
This description should be in the description of the schema ReactionType so that the same description doesn't repeat everywhere.
| type: object | ||
| properties: | ||
| type: | ||
| description: "Specifies the type of social connection. Currently only supports 'follow' to indicate following another user." |
There was a problem hiding this comment.
This description should be on the LinkType schema
| targetFid: | ||
| title: The FID the link relates to | ||
| title: "Target User FID" |
There was a problem hiding this comment.
targetFid and fid should be a single schema that should referenced everywhere else
| allOf: | ||
| - $ref: "#/components/schemas/MessageDataCommon" | ||
| - type: object | ||
| required: | ||
| - linkBody | ||
| properties: | ||
| linkBody: | ||
| description: "Contains the details of the social connection, including the type of relationship and the target user." |
There was a problem hiding this comment.
If the schema already has a description then there is no need to have another description here, unless there is anything specific like targetFid and fid
Co-Authored-By: Team Neynar <[email protected]>
docs: add descriptions/examples for hub-rest-api
Added comprehensive descriptions and examples for all message data schemas in the hub-rest-api OpenAPI specification, including:
Each schema now includes:
Changes have been validated using Spectral and Swagger CLI.
Link to Devin run: https://app.devin.ai/sessions/5db8cfb89a4f49148531fa9d61093125