MT-20082 Add Organizations API to OpenAPI specs #4
Conversation
WalkthroughThe pull request adds a new sub-accounts management feature to the OpenAPI specification by introducing a Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ 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}
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
specs/general.openapi.yml
🧰 Additional context used
📓 Path-based instructions (1)
specs/**/*.openapi.yml
📄 CodeRabbit inference engine (CLAUDE.md)
specs/**/*.openapi.yml: Base URLs must never be changed in OpenAPI specs. Usehttps://send.api.mailtrap.iofor transactional emails,https://bulk.api.mailtrap.iofor bulk emails, andhttps://mailtrap.iofor all other APIs
All documentation links in OpenAPI specs must be absolute URLs pointing to docs.mailtrap.io, not relative links or help.mailtrap.io
Update contact URLs in specinfoblocks to usehttps://docs.mailtrap.io, not help.mailtrap.io
Use GitBook markdown syntax in OpenAPI description fields, ensuring all blocks are properly closed:{% hint %}...{% endhint %}and{% tab %}...{% endtab %}
Tabs cannot be nested inside details blocks when using GitBook syntax in OpenAPI descriptions
Include code samples inx-codeSamplesin this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL
Use official Mailtrap SDKs for language-specific code samples inx-codeSamples, with Node.js (mailtrap/mailtrap-nodejs), PHP (railsware/mailtrap-php), Python (railsware/mailtrap-python), and Ruby (railsware/mailtrap-ruby)
Use environment variables for API keys in code samples (e.g.,process.env.MAILTRAP_API_KEY)
Validate YAML syntax, OpenAPI 3.1 compliance, base URLs, contact URLs, GitBook blocks, links, and code samples before committing OpenAPI spec changes
Do not use emojis in specification content
Keep OpenAPI descriptions concise and developer-focused, with technical accuracy prioritized
Use custom OpenAPI extensions for GitBook navigation:x-page-title,x-page-icon,x-page-description,x-parent,x-codeSamples, andx-logo
Structure tags withx-page-title,x-page-description, andx-parentfor GitBook nested navigation in OpenAPI specs
Use official product naming: 'Email API/SMTP' (can shorten to 'Email API' or 'API/SMTP'), 'Email Sandbox' (can shorten to 'Sandbox'), 'Email Marketing' (can shorten to 'Marketing')
Files:
specs/general.openapi.yml
🪛 Checkov (3.2.334)
specs/general.openapi.yml
[medium] 107-111: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🔇 Additional comments (3)
specs/general.openapi.yml (3)
87-92: LGTM! Tag structure follows conventions.The Organizations tag is properly configured with the required custom extensions for GitBook navigation.
906-918: LGTM! Schema definitions are clear and well-structured.The new schemas follow OpenAPI best practices:
SubAccounthas clear property descriptions and examplesErrorResponseandUnprocessableEntityschemas appropriately represent different error typesAlso applies to: 1053-1067
1098-1107: LGTM! Parameter definition follows established patterns.The
organization_idparameter is properly structured with appropriate validation constraints and matches the pattern used for other ID parameters in the spec.
| get: | ||
| operationId: getOrganizationSubAccounts | ||
| summary: Get organization sub accounts | ||
| description: Get a list of sub accounts for the specified organization. You must have sub account management permissions for this organization. | ||
| tags: | ||
| - Organizations | ||
| responses: | ||
| '200': | ||
| description: Returns the list of sub accounts belonging to the organization. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/SubAccount' | ||
| example: | ||
| - id: 12345 | ||
| name: Development Team Account | ||
| - id: 12346 | ||
| name: QA Team Account | ||
| '401': | ||
| $ref: '#/components/responses/UNAUTHENTICATED' | ||
| '403': | ||
| $ref: '#/components/responses/PERMISSION_DENIED' |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add code samples for the GET operation.
The GET operation is missing x-codeSamples, which are required per coding guidelines. All other operations in this spec include code samples in the priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL.
Add x-codeSamples using the official Mailtrap SDKs with environment variables for API keys (e.g., process.env.MAILTRAP_API_KEY).
Based on coding guidelines: "Include code samples in x-codeSamples in this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL" and "Use official Mailtrap SDKs for language-specific code samples."
🧰 Tools
🪛 Checkov (3.2.334)
[medium] 107-111: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
🤖 Prompt for AI Agents
In specs/general.openapi.yml around lines 95 to 118, the GET operation
getOrganizationSubAccounts is missing the required x-codeSamples block; add an
x-codeSamples array immediately under the operation (same indent as
summary/tags) containing entries in this priority: Node.js, PHP, Python, Ruby,
.NET, Java, cURL; each sample should use the official Mailtrap SDK for that
language, demonstrate calling the getOrganizationSubAccounts endpoint, and
reference the API key via an environment variable (e.g.,
process.env.MAILTRAP_API_KEY for Node.js, getenv('MAILTRAP_API_KEY') or
equivalent for others), include language, label, and a concise code snippet for
each SDK, and ensure examples follow the existing formatting style used
elsewhere in the spec.
| post: | ||
| operationId: createOrganizationSubAccount | ||
| summary: Create organization sub account | ||
| description: Create a new sub account under the specified organization. You must have sub account management permissions for this organization. | ||
| tags: | ||
| - Organizations | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/json: | ||
| schema: | ||
| type: object | ||
| required: | ||
| - account | ||
| properties: | ||
| account: | ||
| type: object | ||
| required: | ||
| - name | ||
| properties: | ||
| name: | ||
| type: string | ||
| description: Name of the sub account to create | ||
| example: New Team Account | ||
| responses: | ||
| '200': | ||
| description: Sub account created successfully. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/SubAccount' | ||
| example: | ||
| id: 12347 | ||
| name: New Team Account | ||
| '400': | ||
| description: Bad request - invalid parameters. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/ErrorResponse' | ||
| '401': | ||
| $ref: '#/components/responses/UNAUTHENTICATED' | ||
| '403': | ||
| $ref: '#/components/responses/PERMISSION_DENIED' | ||
| '422': | ||
| description: Unprocessable entity - validation errors. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/UnprocessableEntity' |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add code samples for the POST operation.
The POST operation is missing x-codeSamples. Code samples are required for all operations to maintain consistency and provide clear usage examples.
Add x-codeSamples demonstrating how to create a sub account using the official Mailtrap SDKs.
Based on coding guidelines: "Include code samples in x-codeSamples in this priority order: Node.js, PHP, Python, Ruby, .NET, Java, cURL."
Motivation:
How to tes:
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.