MT-20453: Add missing cURL code samples and make cURL default option #16
Conversation
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
📝 WalkthroughWalkthroughDocumentation and OpenAPI specs were updated to prioritize cURL in code-sample ordering and to add, remove, or reorganize many cURL (shell) x-codeSamples across multiple specs (contacts, email, email-sending, general, sandbox). Guidance about hardcoding GitBook-generated cURL/HTTP examples was removed. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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
🤖 Fix all issues with AI agents
In `@specs/email-api.openapi.yml`:
- Around line 1266-1276: Add missing language samples for the email template
endpoints: for getEmailTemplate and deleteEmailTemplate add both .NET and Java
examples matching the style used in other endpoints (e.g., sending domains), and
for updateEmailTemplate add both .NET and Java examples plus the Ruby example
present on the other template endpoints; locate the examples blocks for
getEmailTemplate, updateEmailTemplate, and deleteEmailTemplate and insert
corresponding language sections (labelled ".NET"/"C#" and "Java" and "Ruby"
where missing) following the existing snippets' structure and client usage
patterns so the SDK coverage is consistent across all three endpoints.
In `@specs/sandbox.openapi.yml`:
- Around line 116-127: The x-codeSamples blocks currently place cURL first which
violates repo guidelines; for each x-codeSamples occurrence (search for the
x-codeSamples key) reorder the language entries so they follow the required
priority: Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java, then cURL
(shell) as the last sample; update each affected x-codeSamples block accordingly
to move the cURL snippet to the end while preserving the original sample
contents and labels.
🧹 Nitpick comments (1)
specs/email-api.openapi.yml (1)
982-986: Inconsistent authentication header style across endpoints.The templates endpoints use
Api-Token: YOUR_API_KEYwhile domains and suppressions endpoints useAuthorization: Bearer YOUR_API_KEY. Both are valid per the security schemes, but this inconsistency may confuse users following the documentation.Consider standardizing on one authentication style across all cURL examples for consistency, or add a comment explaining when to use each method.
Also applies to: 1073-1087, 1220-1224, 1297-1308, 1406-1410
Comment on lines
+1266
to
+1276
| - lang: ruby | ||
| label: Ruby | ||
| source: | | ||
| curl -X GET "https://mailtrap.io/api/accounts/{account_id}/email_templates/{email_template_id}" \ | ||
| -H "Api-Token: YOUR_API_KEY" | ||
| require 'mailtrap' | ||
|
|
||
| client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY') | ||
| templates = Mailtrap::EmailTemplatesAPI.new( | ||
| YOUR_ACCOUNT_ID, | ||
| client | ||
| ) | ||
| template = templates.get(template_id) |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, let's examine the specific lines mentioned in the review
echo "=== Examining lines 1266-1276 of specs/email-api.openapi.yml ==="
sed -n '1266,1276p' specs/email-api.openapi.yml
echo ""
echo "=== Looking for template endpoints and their code samples ==="
# Search for getEmailTemplate, updateEmailTemplate, deleteEmailTemplate
rg -n "getEmailTemplate|updateEmailTemplate|deleteEmailTemplate" specs/email-api.openapi.yml
echo ""
echo "=== Checking for x-codeSamples blocks near these endpoints ==="
# Look for x-codeSamples in context of template operations
rg -B5 -A30 'getEmailTemplate|updateEmailTemplate|deleteEmailTemplate' specs/email-api.openapi.yml | grep -A30 'x-codeSamples'Repository: mailtrap/mailtrap-openapi
Length of output: 4252
🏁 Script executed:
#!/bin/bash
# Let's get a broader view of code sample coverage for template endpoints
echo "=== Checking ALL code samples in the file for template operations ==="
rg -n 'x-codeSamples:' specs/email-api.openapi.yml | wc -l
echo "Total x-codeSamples blocks found"
echo ""
echo "=== Searching for all template-related operations ==="
rg -n '/(templates|template)' specs/email-api.openapi.yml | grep -E '(post|get|put|patch|delete)' | head -20
echo ""
echo "=== Detailed view of template operations and their samples ==="
# Find operations with 'template' in the path
rg -B2 'operationId.*[Tt]emplate' specs/email-api.openapi.yml | head -100Repository: mailtrap/mailtrap-openapi
Length of output: 793
🏁 Script executed:
#!/bin/bash
# Let's check the specific structure around lines 1266-1276 and beyond
echo "=== Context around the Ruby sample (lines 1250-1300) ==="
sed -n '1250,1300p' specs/email-api.openapi.yml
echo ""
echo "=== Check for .NET (csharp) and Java samples in template operations ==="
rg -B20 'lang: ruby' specs/email-api.openapi.yml | grep -A20 -B20 'template' | grep -E '(lang:|operationId)' | head -40Repository: mailtrap/mailtrap-openapi
Length of output: 2251
🏁 Script executed:
#!/bin/bash
# Search for all csharp and java code samples in the file
echo "=== All .NET (csharp) and Java samples in specs/email-api.openapi.yml ==="
rg -B5 'lang: (csharp|java)' specs/email-api.openapi.yml | head -60
echo ""
echo "=== Count of each language type in the file ==="
rg 'lang: (shell|javascript|php|python|ruby|csharp|java)' specs/email-api.openapi.yml | sed 's/.*lang: //' | sort | uniq -c | sort -rnRepository: mailtrap/mailtrap-openapi
Length of output: 2388
🏁 Script executed:
#!/bin/bash
# Get complete sample list for each template endpoint
echo "=== COMPLETE getEmailTemplate samples ==="
rg -A60 'operationId: getEmailTemplate' specs/email-api.openapi.yml | grep -E '(lang:|operationId)' | head -20
echo ""
echo "=== COMPLETE updateEmailTemplate samples ==="
rg -A60 'operationId: updateEmailTemplate' specs/email-api.openapi.yml | grep -E '(lang:|operationId)' | head -20
echo ""
echo "=== COMPLETE deleteEmailTemplate samples ==="
rg -A60 'operationId: deleteEmailTemplate' specs/email-api.openapi.yml | grep -E '(lang:|operationId)' | head -20Repository: mailtrap/mailtrap-openapi
Length of output: 634
🏁 Script executed:
#!/bin/bash
# Check what samples exist for other major endpoints for comparison
echo "=== Sample coverage for other email API endpoints ==="
rg -B1 'operationId: (sendEmail|send)' specs/email-api.openapi.yml -A50 | grep -E '(operationId|lang:)' | head -30
echo ""
echo "=== Sample coverage for account endpoints ==="
rg -B1 'operationId: (getAccount|getInboxes)' specs/email-api.openapi.yml -A40 | grep -E '(operationId|lang:)' | head -30Repository: mailtrap/mailtrap-openapi
Length of output: 552
Missing .NET and Java code samples on template endpoints.
The getEmailTemplate, updateEmailTemplate, and deleteEmailTemplate endpoints lack .NET and Java samples despite these being present in other endpoints (e.g., sending domains operations). Additionally, updateEmailTemplate is missing the Ruby sample that getEmailTemplate and deleteEmailTemplate include. Add both missing language samples to align with the full SDK coverage across all endpoints.
🤖 Prompt for AI Agents
In `@specs/email-api.openapi.yml` around lines 1266 - 1276, Add missing language
samples for the email template endpoints: for getEmailTemplate and
deleteEmailTemplate add both .NET and Java examples matching the style used in
other endpoints (e.g., sending domains), and for updateEmailTemplate add both
.NET and Java examples plus the Ruby example present on the other template
endpoints; locate the examples blocks for getEmailTemplate, updateEmailTemplate,
and deleteEmailTemplate and insert corresponding language sections (labelled
".NET"/"C#" and "Java" and "Ruby" where missing) following the existing
snippets' structure and client usage patterns so the SDK coverage is consistent
across all three endpoints.
Contributor
Author
There was a problem hiding this comment.
I'll address this separetely with our SDK maintainers
There was a problem hiding this comment.
@mklocek, sounds good! Coordinating with the SDK maintainers is the right approach to ensure the code samples match the actual SDK implementations. Feel free to tag me if you need any assistance when you address this.
🧠 Learnings used
Learnt from: mklocek
Repo: mailtrap/mailtrap-openapi PR: 16
File: specs/sandbox.openapi.yml:116-127
Timestamp: 2026-01-28T15:18:12.895Z
Learning: Applies to specs/**/*.openapi.yml : Include code samples in x-codeSamples in this priority order: cURL (shell), Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java. cURL should always be the first option (default) to align with Mailtrap's in-app integration samples.
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-28T13:27:41.683Z
Learning: Applies to specs/**/*.openapi.yml : Use official Mailtrap SDKs for language-specific code examples in x-codeSamples. Use environment variables for API keys (e.g., process.env.MAILTRAP_API_KEY)
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-28T13:27:41.683Z
Learning: Applies to specs/**/*.openapi.yml : Validate YAML syntax, verify correct base URLs, update contact URLs to docs.mailtrap.io, validate GitBook blocks are properly opened and closed, check all links are absolute and valid, verify SDK code samples match current versions, and test with OpenAPI 3.1 validator
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-28T13:27:41.683Z
Learning: Applies to specs/**/*.openapi.yml : Include code samples in x-codeSamples in this priority order: Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java, cURL (shell)
leonid-shevtsov
approved these changes
Jan 28, 2026
leonid-shevtsov
left a comment
leonid-shevtsov
left a comment
There was a problem hiding this comment.
would be awesome to have an integration test
IgorDobryn
approved these changes
Jan 29, 2026
…(first on the list)
mklocek
force-pushed
the
MT-20453-make-c-url-default-option-in-the-samples
branch
from
75ae745 to
5d9eccb
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@specs/email-api.openapi.yml`:
- Around line 1266-1276: Add explicit definitions for the template ID variables
used in the Ruby samples: before calling Mailtrap::EmailTemplatesAPI#get, define
either template_id = 'YOUR_TEMPLATE_ID' (for the snake_case example) or
EMAIL_TEMPLATE_ID = 'YOUR_TEMPLATE_ID' (for the constant-style example) so the
snippets are runnable; update every occurrence where
Mailtrap::EmailTemplatesAPI.new(...); template = templates.get(template_id) or
templates.get(EMAIL_TEMPLATE_ID) is used to include the corresponding
variable/constant declaration immediately above the API usage (references:
Mailtrap::Client, Mailtrap::EmailTemplatesAPI, template_id, EMAIL_TEMPLATE_ID).
🧹 Nitpick comments (1)
.claude/skills/gitbook-assistant/.SKILL.md (1)
256-256: Consider clarifying the relationship with line 248 and repositioning.The directive "If SDK doesn't support some method - mention it in code sample" is useful, but its relationship to line 248's guidance ("If some API method isn't covered with Node.JS SDK and Python SDK - let Gitbook generate those examples") could be clearer. Additionally, positioning this SDK-related directive after the OpenAPI/GitBook markup section (lines 252-255) breaks the logical flow.
Consider:
- Moving this closer to line 248 to group SDK-related guidance together
- Clarifying when to "let GitBook generate" vs. "mention in code sample" (e.g., "For languages other than Node.js/Python, if SDK doesn't support a method, mention it in the code sample")
📝 Example clarification
- Use SDKs for language-specific client libraries examples - Prioritize such languages in this order: cURL, Node.js, PHP, Python, Ruby, .NET, Java -- If some API method isn't covered with Node.JS SDK and Python SDK - let Gitbook generate those examples +- If some API method isn't covered with Node.JS SDK and Python SDK - let Gitbook generate those examples automatically +- For other languages, if SDK doesn't support some method - mention it in the code sample - Use code samples based on Mailtrap SDK examples - Use Context7 MCP to query info about SDK capabilities - Use SDK repos for language-specific client libraries those are places in /openapi/sdks/ directory - Add Gitbook markup in OpenAPI specs, use Gitbook skill - Add reference to features in the OpenAPI spec and build relative links to them to the relevant sections of the documentation - Build OpenAPI specs file(s) in /openapi/ directory - They or one for all will be imported into the Gitbook documentation -- If SDK doesn't support some method - mention it in code sample
Comment on lines
+1266
to
+1276
| - lang: ruby | ||
| label: Ruby | ||
| source: | | ||
| curl -X GET "https://mailtrap.io/api/accounts/{account_id}/email_templates/{email_template_id}" \ | ||
| -H "Api-Token: YOUR_API_KEY" | ||
| require 'mailtrap' | ||
|
|
||
| client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY') | ||
| templates = Mailtrap::EmailTemplatesAPI.new( | ||
| YOUR_ACCOUNT_ID, | ||
| client | ||
| ) | ||
| template = templates.get(template_id) |
There was a problem hiding this comment.
Define template ID variables in Ruby samples.
The Ruby snippets reference template_id / EMAIL_TEMPLATE_ID without defining them, which makes the examples non-runnable.
Proposed fix
- lang: ruby
label: Ruby
source: |
require 'mailtrap'
client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY')
templates = Mailtrap::EmailTemplatesAPI.new(
YOUR_ACCOUNT_ID,
client
)
+ template_id = "YOUR_TEMPLATE_ID"
template = templates.get(template_id) - lang: ruby
label: Ruby
source: |
require 'mailtrap'
client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY')
templates = Mailtrap::EmailTemplatesAPI.new(
YOUR_ACCOUNT_ID,
client
)
+ EMAIL_TEMPLATE_ID = "YOUR_TEMPLATE_ID"
templates.update(EMAIL_TEMPLATE_ID, name: 'Welcome Updated') - lang: ruby
label: Ruby
source: |
require 'mailtrap'
client = Mailtrap::Client.new(api_key: 'YOUR_API_KEY')
templates = Mailtrap::EmailTemplatesAPI.new(
YOUR_ACCOUNT_ID,
client
)
+ EMAIL_TEMPLATE_ID = "YOUR_TEMPLATE_ID"
templates.delete(EMAIL_TEMPLATE_ID)Also applies to: 1368-1378, 1453-1462
🤖 Prompt for AI Agents
In `@specs/email-api.openapi.yml` around lines 1266 - 1276, Add explicit
definitions for the template ID variables used in the Ruby samples: before
calling Mailtrap::EmailTemplatesAPI#get, define either template_id =
'YOUR_TEMPLATE_ID' (for the snake_case example) or EMAIL_TEMPLATE_ID =
'YOUR_TEMPLATE_ID' (for the constant-style example) so the snippets are
runnable; update every occurrence where Mailtrap::EmailTemplatesAPI.new(...);
template = templates.get(template_id) or templates.get(EMAIL_TEMPLATE_ID) is
used to include the corresponding variable/constant declaration immediately
above the API usage (references: Mailtrap::Client, Mailtrap::EmailTemplatesAPI,
template_id, EMAIL_TEMPLATE_ID).
Contributor
Author
There was a problem hiding this comment.
Not related to this PR, I'll let our SDK maintainer know
There was a problem hiding this comment.
@mklocek, understood! Thank you for acknowledging the issue and for letting the SDK maintainer know. Since it's pre-existing and outside the scope of this PR's cURL additions, that makes perfect sense. 👍
🧠 Learnings used
Learnt from: mklocek
Repo: mailtrap/mailtrap-openapi PR: 16
File: specs/sandbox.openapi.yml:116-127
Timestamp: 2026-01-28T15:18:12.895Z
Learning: Applies to specs/**/*.openapi.yml : Include code samples in x-codeSamples in this priority order: cURL (shell), Node.js (JavaScript), PHP, Python, Ruby, .NET (C#), Java. cURL should always be the first option (default) to align with Mailtrap's in-app integration samples.
Learnt from: CR
Repo: mailtrap/mailtrap-openapi PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-28T13:27:41.683Z
Learning: Applies to specs/**/*.openapi.yml : Use official Mailtrap SDKs for language-specific code examples in x-codeSamples. Use environment variables for API keys (e.g., process.env.MAILTRAP_API_KEY)
Learnt from: dr-3lo
Repo: mailtrap/mailtrap-openapi PR: 9
File: specs/email-sending-bulk.openapi.yml:159-170
Timestamp: 2025-12-29T15:56:59.597Z
Learning: Applies to specs/**/*.openapi.yml: In x-codeSamples code examples, use placeholder strings like "YOUR_API_KEY", "YOUR_ACCOUNT_ID", etc. rather than environment variables for clarity in documentation examples.
GannaRW
approved these changes
Jan 29, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Motivation
Bring consistency in API docs and default to cURL code samples - same as it is in Mailtrap's in-app integration samples.
Changes
How to test
Images and GIFs
None.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.