Extract inline response schemas into named component schemas#114
Open
LukasParke wants to merge 1 commit intomainfrom
Open
Extract inline response schemas into named component schemas#114LukasParke wants to merge 1 commit intomainfrom
LukasParke wants to merge 1 commit intomainfrom
Conversation
…hemas Extract 29 new named schemas from inline definitions, eliminating duplication and ensuring Speakeasy SDKs generate proper named model classes instead of anonymous inline types. Phase 1 - Deduplicated schemas: - DVR (8 identical copies → 1 schema) - DecisionResult + DownloadQueueItem (2 copies each) - DownloadQueue (2 copies) - PlaybackHistoryMetadata (2 divergent copies reconciled to 16-property superset) Phase 2 - Single-use inline extractions: - Activity, TranscodeJob, ButlerTask, UltraBlurColors - EPGCountry, EPGLanguage, EPGRegion - MediaGrabber, DeviceChannel, Marker, TopUserAccount - Release, PlayQueueResponse, Bandwidth, AddedQueueItem, Level - Connection, ConnectionInfo, ConnectionInfoWrapper - Feature, ManagedHub Phase 3 - Fixed existing schema references: - MediaContainerWithDevice now uses $ref to Device schema - 7 Hub endpoints → $ref MediaContainerWithHubs - Directory/Sort/Tag/MediaGrabOperation endpoints → new wrapper schemas Net result: -299 lines (960 removed, 661 added), 45 → 74 total schemas. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
📝 WalkthroughWalkthroughI trust this revision shall prove most gratifying, sir. The specification has undergone a most thorough modernisation, wherein numerous inline schema definitions have been supplanted with formal public component references throughout the document. One has introduced seven-and-twenty new public entity schemas whilst standardising their deployment across multiple endpoints, thereby extending the API's public surface with considerably greater consistency and propriety. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plex-api-spec.yaml`:
- Around line 8024-8026: The response schema for the filters endpoint currently
uses MediaContainerWithDirectory which types each entry as Directory; update the
OpenAPI wrapper so the MediaContainer's Directory array maps to the existing
Filter schema instead of Directory (i.e. change the component reference under
MediaContainerWithDirectory's Directory items from Directory to Filter
/#/components/schemas/Filter) so generated models expose filterType, descKey and
other Filter fields; update any references in MediaContainerWithDirectory and
components/schemas to reflect Directory[] -> Filter[] for this endpoint.
- Around line 3085-3087: The response schema composing MediaContainer and
PlayQueueResponse has dropped the initial queue items; update the allOf
composition to also include the response Metadata array so clients receive the
queue contents returned by createPlayQueue. Specifically, modify the wrapper
that currently references MediaContainer and PlayQueueResponse to additionally
reference or define the Metadata array component (the same array used elsewhere
for item metadata) so the composed schema contains MediaContainer,
PlayQueueResponse, and the Metadata array.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0480fe1a-f34f-4f63-8e21-8ecc6b671128
📒 Files selected for processing (1)
plex-api-spec.yaml
Comment on lines
3085
to
+3087
| allOf: | ||
| - $ref: '#/components/schemas/MediaContainer' | ||
| - properties: | ||
| playQueueID: | ||
| description: The ID of the play queue, which is used in subsequent requests. | ||
| type: integer | ||
| playQueueLastAddedItemID: | ||
| description: Defines where the "Up Next" region starts | ||
| type: string | ||
| playQueueSelectedItemID: | ||
| description: The queue item ID of the currently selected item. | ||
| type: integer | ||
| playQueueSelectedItemOffset: | ||
| description: The offset of the selected item in the play queue, from the beginning of the queue. | ||
| type: integer | ||
| playQueueSelectedMetadataItemID: | ||
| description: The metadata item ID of the currently selected item (matches `ratingKey` attribute in metadata item if the media provider is a library). | ||
| type: integer | ||
| playQueueShuffled: | ||
| description: Whether or not the queue is shuffled. | ||
| type: boolean | ||
| playQueueSourceURI: | ||
| description: The original URI used to create the play queue. | ||
| type: string | ||
| playQueueTotalCount: | ||
| description: The total number of items in the play queue. | ||
| type: integer | ||
| playQueueVersion: | ||
| description: The version of the play queue. It increments every time a change is made to the play queue to assist clients in knowing when to refresh. | ||
| type: integer | ||
| type: object | ||
| - $ref: '#/components/schemas/PlayQueueResponse' |
Contributor
There was a problem hiding this comment.
Pray restore the queue items in this response.
Line 3087 composes MediaContainer with PlayQueueResponse only, so the Metadata array promised by createPlayQueue is no longer part of the schema. Generated clients will expose the queue metadata but not the initial queue contents.
Suggested adjustment
- properties:
- MediaContainer:
- allOf:
- - $ref: '#/components/schemas/MediaContainer'
- - $ref: '#/components/schemas/PlayQueueResponse'
- type: object
+ $ref: '#/components/schemas/MediaContainerWithPlayQueue'That wrapper should compose #/components/schemas/MediaContainer, #/components/schemas/PlayQueueResponse, and the response Metadata array.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plex-api-spec.yaml` around lines 3085 - 3087, The response schema composing
MediaContainer and PlayQueueResponse has dropped the initial queue items; update
the allOf composition to also include the response Metadata array so clients
receive the queue contents returned by createPlayQueue. Specifically, modify the
wrapper that currently references MediaContainer and PlayQueueResponse to
additionally reference or define the Metadata array component (the same array
used elsewhere for item metadata) so the composed schema contains
MediaContainer, PlayQueueResponse, and the Metadata array.
Comment on lines
8024
to
+8026
| application/json: | ||
| schema: | ||
| properties: | ||
| MediaContainer: | ||
| allOf: | ||
| - $ref: '#/components/schemas/MediaContainer' | ||
| - properties: | ||
| Directory: | ||
| items: | ||
| $ref: '#/components/schemas/Directory' | ||
| type: array | ||
| type: object | ||
| type: object | ||
| $ref: '#/components/schemas/MediaContainerWithDirectory' |
Contributor
There was a problem hiding this comment.
This wrapper is too general for the filters endpoint.
Lines 8024-8026 now point at MediaContainerWithDirectory, which types each entry as a plain Directory. This route returns filter descriptors, and the spec already has a Filter schema for fields such as filterType and descKey; otherwise the generated models lose that typed surface.
Suggested adjustment
- schema:
- $ref: '#/components/schemas/MediaContainerWithDirectory'
+ schema:
+ $ref: '#/components/schemas/MediaContainerWithFilters'That wrapper should map MediaContainer.Directory[] to #/components/schemas/Filter.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plex-api-spec.yaml` around lines 8024 - 8026, The response schema for the
filters endpoint currently uses MediaContainerWithDirectory which types each
entry as Directory; update the OpenAPI wrapper so the MediaContainer's Directory
array maps to the existing Filter schema instead of Directory (i.e. change the
component reference under MediaContainerWithDirectory's Directory items from
Directory to Filter /#/components/schemas/Filter) so generated models expose
filterType, descKey and other Filter fields; update any references in
MediaContainerWithDirectory and components/schemas to reflect Directory[] ->
Filter[] for this endpoint.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
MediaContainerWithDeviceto reference the existingDeviceschema instead of redefining it inlineMediaContainerWith*wrapper schemas via$refDetails
Phase 1 — Deduplicated schemas (highest value)
DVRDecisionResultDownloadQueueItemDownloadQueueItem$reftoDecisionResultDownloadQueuePlaybackHistoryMetadataPhase 2 — Single-use inline extractions (22 schemas)
Each of these was defined inline in a single endpoint response and is now a named schema:
Activity,TranscodeJob,ButlerTask,UltraBlurColors,EPGCountry,EPGLanguage,EPGRegion,MediaGrabber,DeviceChannel,Marker,TopUserAccount,Release,PlayQueueResponse,Bandwidth,AddedQueueItem,Level,Connection,ConnectionInfo,ConnectionInfoWrapper,Feature,ManagedHubPhase 3 — Fixed existing schema references
MediaContainerWithDevice: Replaced 14-property inline Device definition with$ref: '#/components/schemas/Device'(byte-for-byte identical)$ref: MediaContainerWithHubs$ref: MediaContainerWithDirectoryMediaContainerWithSorts,MediaContainerWithTags,MediaContainerWithMediaGrabOperationWhat was NOT changed
Key,Thumb,Title,Type,BoolInt,AllowSync)Metadataschema internal structureMedia/Part/StreamhierarchyPlayervsDevice— fundamentally different conceptsImpact
Test plan
python3 -c "import yaml; yaml.safe_load(open('plex-api-spec.yaml'))"components/schemasspeakeasy lint openapi --schema plex-api-spec.yaml🤖 Generated with Claude Code
Summary by CodeRabbit