feat:Update documentation references in OpenAPI schema#154
Merged
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
WalkthroughUpdated descriptions and documentation references across numerous schema fields in the OpenAPI specification file to point to current documentation paths. Changes include revised URLs for language-related fields, feature descriptors, translation, speaker identification, and transcript-related schemas. No functional or structural changes to the API. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
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
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/libs/AssemblyAI/openapi.yaml (1)
3149-3157:⚠️ Potential issue | 🟠 MajorModel
translated_textsas a map, not a fixedlanguage_codeproperty.The updated description says this object is keyed by language code, but the schema still defines a single literal
language_codeproperty. That will generate the wrong response type in docs/SDKs, especially sinceTranscriptUtterance.translated_textsalready models the same concept as a string map.🛠 Proposed fix
translated_texts: # x-label: Translated text type: object description: Translated text keyed by language code. See [Translation](https://www.assemblyai.com/docs/speech-understanding/translation) for more details. - properties: - language_code: - x-label: Language code - type: string - description: Translated text for this language code + additionalProperties: + type: string🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/libs/AssemblyAI/openapi.yaml` around lines 3149 - 3157, The schema for translated_texts is incorrectly modeled with a fixed property language_code; change it to a map keyed by language codes by removing the literal language_code property and using additionalProperties: { type: string } (or patternProperties if you want a language-code regex) so translated_texts becomes an object map of strings (matching how TranscriptUtterance.translated_texts is modeled) and update the description/labels accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/libs/AssemblyAI/openapi.yaml`:
- Around line 1389-1392: The description for the fallback_language field in
src/libs/AssemblyAI/openapi.yaml contradicts its schema: the field is defined as
type: string (fallback_language) with default: "auto", but the prose instructs
consumers to pass ["auto"]. Update the description text for the
fallback_language property (both instances referencing fallback_language) to
indicate the single string value "auto" (not an array ["auto"]) and ensure the
wording matches the schema and default; no schema change is required—only
correct the descriptive text around fallback_language to reference the string
"auto".
- Around line 1467-1473: The docs for redact_pii_sub advertise an `entity_type`
option that is not allowed by the SubstitutionPolicy enum; update the text to
match the enum (use `entity_name` and `hash`) or alternatively add `entity_type`
to the SubstitutionPolicy enum—make the change consistently for the
redact_pii_sub entries (the one under redact_pii_sub and the other occurrence
around lines 2944-2947) and ensure the description and oneOf/default reflect the
same allowed values as the SubstitutionPolicy schema.
---
Outside diff comments:
In `@src/libs/AssemblyAI/openapi.yaml`:
- Around line 3149-3157: The schema for translated_texts is incorrectly modeled
with a fixed property language_code; change it to a map keyed by language codes
by removing the literal language_code property and using additionalProperties: {
type: string } (or patternProperties if you want a language-code regex) so
translated_texts becomes an object map of strings (matching how
TranscriptUtterance.translated_texts is modeled) and update the
description/labels accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9eb41ff6-4b7f-4226-9454-a254b050198b
⛔ Files ignored due to path filters (25)
src/libs/AssemblyAI/Generated/AssemblyAI.Models.AutoHighlightsResult2.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.ContentSafetyLabelsResult.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.CustomFormattingRequestBody.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.CustomFormattingRequestBodyCustomFormatting.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.RedactPiiAudioQuality.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.SentimentAnalysisResult.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.SpeakerIdentificationRequestBody.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.SpeakerIdentificationRequestBodySpeakerIdentification.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.SpeakerIdentificationRequestBodySpeakerIdentificationSpeakerType.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.SubstitutionPolicy.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TopicDetectionModelResult.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.Transcript.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptLanguageCode.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptLanguageDetectionOptions.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptOptionalParams.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptOptionalParamsLanguageDetectionOptions.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptOptionalParamsRedactPiiAudioOptions.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptOptionalParamsSpeakerOptions.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptOptionalParamsSpeechUnderstanding.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptSentence.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptSpeechUnderstanding.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptTranslatedTexts.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranscriptWord.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranslationRequestBody.g.csis excluded by!**/generated/**src/libs/AssemblyAI/Generated/AssemblyAI.Models.TranslationRequestBodyTranslation.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/AssemblyAI/openapi.yaml
Comment on lines
1389
to
1392
| x-label: Fallback language | ||
| description: | | ||
| If the detected language of the audio file is not in the list of expected languages, the `fallback_language` is used. Specify `["auto"]` to let our model choose the fallback language from `expected_languages` with the highest confidence score. | ||
| If the detected language of the audio file is not in the list of expected languages, the `fallback_language` is used. Specify `["auto"]` to let our model choose the fallback language from `expected_languages` with the highest confidence score. See [Automatic Language Detection](https://www.assemblyai.com/docs/pre-recorded-audio/language-detection) for more details. | ||
| type: string |
There was a problem hiding this comment.
Document fallback_language as a string, not an array.
Line 1391 and Line 2877 now tell users to pass ["auto"], but this field is declared as type: string with default: "auto". That makes the published contract self-contradictory and will lead consumers to send an invalid payload.
🛠 Proposed fix
- If the detected language of the audio file is not in the list of expected languages, the `fallback_language` is used. Specify `["auto"]` to let our model choose the fallback language from `expected_languages` with the highest confidence score. See [Automatic Language Detection](https://www.assemblyai.com/docs/pre-recorded-audio/language-detection) for more details.
+ If the detected language of the audio file is not in the list of expected languages, the `fallback_language` is used. Specify `"auto"` to let our model choose the fallback language from `expected_languages` with the highest confidence score. See [Automatic Language Detection](https://www.assemblyai.com/docs/pre-recorded-audio/language-detection) for more details.Also applies to: 2875-2878
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/libs/AssemblyAI/openapi.yaml` around lines 1389 - 1392, The description
for the fallback_language field in src/libs/AssemblyAI/openapi.yaml contradicts
its schema: the field is defined as type: string (fallback_language) with
default: "auto", but the prose instructs consumers to pass ["auto"]. Update the
description text for the fallback_language property (both instances referencing
fallback_language) to indicate the single string value "auto" (not an array
["auto"]) and ensure the wording matches the schema and default; no schema
change is required—only correct the descriptive text around fallback_language to
reference the string "auto".
Comment on lines
1467
to
1473
| redact_pii_sub: | ||
| x-label: Redact PII substitution | ||
| description: The replacement logic for detected PII, can be `entity_type` or `hash`. See [PII redaction](https://www.assemblyai.com/docs/models/pii-redaction) for more details. | ||
| description: The replacement logic for detected PII, can be `entity_type` or `hash`. See [PII redaction](https://www.assemblyai.com/docs/pii-redaction) for more details. | ||
| oneOf: | ||
| - $ref: "#/components/schemas/SubstitutionPolicy" | ||
| - type: "null" | ||
| default: hash |
There was a problem hiding this comment.
Keep redact_pii_sub docs aligned with the enum values.
These descriptions now say the field accepts entity_type, but SubstitutionPolicy still only allows entity_name | hash (see Line 1993). That means the generated docs will advertise a value the schema rejects.
🛠 Proposed fix
- description: The replacement logic for detected PII, can be `entity_type` or `hash`. See [PII redaction](https://www.assemblyai.com/docs/pii-redaction) for more details.
+ description: The replacement logic for detected PII, can be `entity_name` or `hash`. See [PII redaction](https://www.assemblyai.com/docs/pii-redaction) for more details.Also applies to: 2944-2947
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/libs/AssemblyAI/openapi.yaml` around lines 1467 - 1473, The docs for
redact_pii_sub advertise an `entity_type` option that is not allowed by the
SubstitutionPolicy enum; update the text to match the enum (use `entity_name`
and `hash`) or alternatively add `entity_type` to the SubstitutionPolicy
enum—make the change consistently for the redact_pii_sub entries (the one under
redact_pii_sub and the other occurrence around lines 2944-2947) and ensure the
description and oneOf/default reflect the same allowed values as the
SubstitutionPolicy schema.
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 by CodeRabbit