feat:Update OpenAPI specification by removing multiple schema definitions and modifying responses #70
Conversation
WalkthroughThe pull request introduces significant modifications to the OpenAPI specification for the AI21 Studio API. It involves the removal of several schema definitions, including those for Changes
Possibly related PRs
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
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: 1
🧹 Outside diff range and nitpick comments (4)
src/libs/AI21/openapi.yaml (4)
Line range hint
516-516: Fix duplicate operation ID.The operation ID
v1_j2_jumbo_completeis used for both the standard and custom model endpoints. This can cause issues with code generation tools and SDK creation.Update one of the operation IDs to be unique. For example:
- operationId: v1_j2_jumbo_complete + operationId: v1_j2_jumbo_custom_model_completeAlso applies to: 516-516
Line range hint
1223-1225: Enhance API security measures.While the API implements Bearer token authentication, consider adding:
- Rate limiting specifications
- File size and type validations for upload endpoints
- Token expiration and refresh mechanisms
- CORS policy definitions
Consider adding security schemas and headers using OpenAPI security schemes and global security requirements.
Line range hint
32-38: Improve endpoint documentation consistency.While some endpoints like
/studio/v1/chat/completionshave detailed descriptions, others lack proper documentation. This inconsistency makes it harder for API consumers to understand the full functionality.Add comprehensive descriptions for all endpoints, including:
- Expected behavior
- Request/response examples
- Error scenarios
- Rate limiting details
- Use cases
Also applies to: 516-520
Line range hint
1-20: Enhance OpenAPI specification quality.Consider the following improvements to align better with OpenAPI best practices:
- Add API description fields like
contact,license, andtermsOfService- Include
externalDocsfor additional documentation- Add example values for request/response schemas
- Use consistent casing for property names (some use camelCase, others use snake_case)
Add metadata fields at the root level:
openapi: 3.0.1 info: title: AI21 Studio API description: Access our powerful language models using an API that makes you smile version: 1.0.0 + contact: + name: AI21 Support + url: https://www.ai21.com/support + email: [email protected] + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + termsOfService: https://www.ai21.com/terms +externalDocs: + description: API Documentation + url: https://docs.ai21.com/
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
⛔ Files ignored due to path filters (36)
src/libs/AI21/Generated/AI21.ILibraryManagementClient.V1LibraryDelete.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.ILibraryManagementClient.V1LibraryUpload.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.IRAGEngineClient.V1LibraryAnswer.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.IRAGEngineClient.V1LibrarySearch.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.LibraryManagementClient.V1LibraryDelete.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.LibraryManagementClient.V1LibraryUpload.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.AnswerLength.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.FileDeleteResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.FileUploadResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibraryAnswerRequest.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibraryAnswerRequestLabelsFilterMode.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibraryAnswerResponse.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibraryAnswerResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibrarySearchResponse.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibrarySearchResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibrarySearchResult.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.LibrarySearchResult.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.Mode.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.SourceDocument.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.SourceDocument.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.V1LibraryDeleteResponse.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.V1LibraryDeleteResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.V1LibrarySearchResponse.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.V1LibrarySearchResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.V1LibraryUploadResponse.Json.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.Models.V1LibraryUploadResponse.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.RAGEngineClient.V1LibraryAnswer.g.csis excluded by!**/generated/**src/libs/AI21/Generated/AI21.RAGEngineClient.V1LibrarySearch.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonConverters.AnswerLength.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonConverters.AnswerLengthNullable.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonConverters.LibraryAnswerRequestLabelsFilterMode.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonConverters.LibraryAnswerRequestLabelsFilterModeNullable.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonConverters.Mode.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonConverters.ModeNullable.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonSerializerContext.g.csis excluded by!**/generated/**src/libs/AI21/Generated/JsonSerializerContextTypes.g.csis excluded by!**/generated/**
📒 Files selected for processing (1)
src/libs/AI21/openapi.yaml(3 hunks)
| @@ -1072,8 +1072,7 @@ paths: | |||
| description: Successful Response | |||
| content: | |||
| application/json: | |||
| schema: | |||
| $ref: '#/components/schemas/FileUploadResponse' | |||
| schema: { } | |||
There was a problem hiding this comment.
Define response schemas for endpoints.
Multiple endpoints are using empty response schemas ({}). This includes critical endpoints like file upload and search operations. Empty schemas make it difficult for clients to:
- Validate responses
- Understand the expected response format
- Handle responses properly
Consider defining proper response schemas that accurately represent the data returned by these endpoints. For example, the file upload endpoint should likely return metadata about the uploaded file.
Also applies to: 1179-1179, 1210-1210
Summary by CodeRabbit
New Features
Bug Fixes
Upload Organization FileandSearchendpoints to a more generic format.Documentation