Skip to content

MT-20082 Add Organizations API to OpenAPI specs #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yanchuk merged 1 commit into from
Dec 24, 2025
Merged

MT-20082 Add Organizations API to OpenAPI specs #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 121 additions & 0 deletions specs/general.openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,90 @@ tags:
x-page-title: Billing
x-page-description: Billing information
description: Account Billing

- name: Organizations
x-parent: general-api
x-page-title: Organizations
x-page-description: Organization Sub Accounts management
description: Create and manage organization sub accounts
paths:
'/api/organizations/{organization_id}/sub_accounts':
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'
Comment on lines +95 to +118
Copy link

@coderabbitai coderabbitai bot Dec 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ 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'
Comment on lines +119 to +168
Copy link

@coderabbitai coderabbitai bot Dec 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ 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."

parameters:
- $ref: '#/components/parameters/organization_id'
/api/accounts:
get:
operationId: getAllAccounts
Expand Down Expand Up @@ -820,6 +903,19 @@ paths:
- $ref: '#/components/parameters/account_id'
components:
schemas:
SubAccount:
title: SubAccount
description: Represents a sub account within an organization
type: object
properties:
id:
type: integer
example: 12345
description: The unique identifier of the sub account
name:
type: string
example: Development Team Account
description: The name of the sub account
AccountAccess:
title: AccountAccess
description: Assigns resource-specific permissions to a specifier.
Expand Down Expand Up @@ -954,6 +1050,21 @@ components:
type: string
description: Error message
example: Incorrect API token
ErrorResponse:
title: ErrorResponse
type: object
properties:
errors:
type: string
description: Error message
example: Unexpected error
UnprocessableEntity:
title: UnprocessableEntity
type: object
properties:
errors:
type: object
description: Validation errors per attribute. Entire record errors are under `base` key.
securitySchemes:
HeaderAuth:
type: apiKey
Expand Down Expand Up @@ -984,6 +1095,16 @@ components:
schema:
$ref: '#/components/schemas/NotFoundResponse'
parameters:
organization_id:
description: Unique organization ID
name: organization_id
in: path
required: true
schema:
type: integer
format: int64
minimum: 1
example: 1001
account_id:
description: Unique account ID
name: account_id
Expand Down
Loading