Sync open source content 🐝 (from fd76fdc4bed478dc4d812f0cc65f254d4ba0f624)

Author: beezythebot

api-design/developer-experience.mdx

@@ -27,9 +27,9 @@ Stripe offers well-maintained SDKs for major programming languages and framework
 
 For example, here's how to create a payment intent using Stripe's Python SDK compared to making a raw API request:
 
-<div className="md:flex gap-10">
-  <div className="md:w-1/2">
-```python stripe_sdk_example.py
+<div className="min-[1660px]:flex gap-6 justify-center [&>div]:min-[1660px]:max-w-[50%]">
+  <div>
+```python filename="stripe_sdk_example.py"
 import stripe
 
 stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"
@@ -39,12 +39,10 @@ amount=1000,
 currency="usd",
 payment_method_types=["card"],
 )
-
-````
-
+```
   </div>
-  <div className="md:w-1/2">
-```python stripe_api_example.py
+  <div>
+```python filename="stripe_api_example.py"
 import requests
 
 url = "https://api.stripe.com/v1/payment_intents"
@@ -58,7 +56,7 @@ data = {
 }
 response = requests.post(url, headers=headers, data=data)
 print(response.json())
-````
+```
 
   </div>
 </div>

api-design/picking-architectures.mdx

@@ -42,7 +42,7 @@ Beyond authentication, REST's resource-oriented design provides an intuitive and
 
 For example, you can use the Flask framework in Python to build a RESTful API. Here is how you can define a simple endpoint to fetch a list of products:
 
-```python app.py
+```python filename="app.py"
 from flask import Flask, jsonify, request
 
 app = Flask(__name__)
@@ -262,7 +262,7 @@ This is what a typical WebSocket architecture looks like.
 
 WebSockets is a great choice for our high-frequency trading application. Let's see how this could be implemented in a Node.js application, using channels to allow users to send orders and receive price changes in real time.
 
-```javascript app.js
+```javascript filename="app.js"
 import {WebSocketServer} from 'ws';
 import Redis from 'ioredis';
 

api-design/testing.mdx

@@ -3,6 +3,8 @@ title: "Testing Best Practices in REST API Design"
 description: "Implement comprehensive API testing strategies to ensure reliability, performance, and backward compatibility throughout development cycles."
 ---
 
+import Image from "next/image";
+
 # Testing your API
 
 We write tests to build trust. Trust that our software is reliable, safe, and extendable. When it comes to testing public APIs, robust testing gives users confidence that the API *behaves* as expected. This guide not only covers the *how* of API testing, but also how to project externally the confidence brought by testing.
@@ -17,7 +19,7 @@ But for *public* or third-party-consumed APIs, the *why* extends further. Your t
 
 API testing clashes with the traditional test pyramid - you know, the one that says, "Many unit tests at the bottom, fewer integration tests in the middle, and a few end-to-end tests at the top."
 
-![The test pyramid](/assets/api-design/api-testing/pyramid.svg?.url)
+<Image src="/assets/api-design/api-testing/pyramid.svg?.url" alt="The test pyramid" width={1000} height={1000} />
 
 This pyramid is a good model for verifying the implementation details of small units of work, but it's a terrible model for verifying an API's behavior. Unit tests, useful on the server when testing complex logic, don't tell us much about how the API behaves as a whole.
 
@@ -27,7 +29,7 @@ We need a new model for API tests.
 
 The traditional test pyramid (many unit tests, fewer integration tests, fewest E2E tests) is okay for internal implementation details. But for verifying API *behavior* from a consumer's viewpoint, the emphasis shifts.
 
-![API test pyramid](/assets/api-design/api-testing/api-pyramid.svg?.url)
+<Image src="/assets/api-design/api-testing/api-pyramid.svg?.url" alt="The API test pyramid" width={1000} height={1000} />
 
 It's not exactly a pyramid, but you get the idea.
 
@@ -298,7 +300,7 @@ Here's what belongs in the public domain:
 
 ✅ **Authentication flow verification:** Tests that demonstrate how authentication works, covering token acquisition, refresh flows, and error handling.
 
-```python auth_flow_test.py
+```python filename="auth_flow_test.py"
 def test_invalid_api_key_returns_401():
     client = ApiClient(api_key="invalid_key")
     response = client.users.list()
@@ -309,7 +311,7 @@ def test_invalid_api_key_returns_401():
 
 ✅ **Rate limit behavior tests:** Tests that verify how your API behaves when rate limits are approached or exceeded.
 
-```python rate_limit_test.py
+```python filename="rate_limit_test.py"
 def test_rate_limit_headers_present():
     response = client.resources.list()
     assert "X-RateLimit-Limit" in response.headers
@@ -319,7 +321,7 @@ def test_rate_limit_headers_present():
 
 ✅ **Error condition handling:** Tests that demonstrate how your API responds to different error states, such as invalid inputs, missing resources, and service errors.
 
-```python error_handling_test.py
+```python filename="error_handling_test.py"
 def test_resource_not_found():
     response = client.products.get(id="nonexistent")
     assert response.status_code == 404
@@ -329,7 +331,7 @@ def test_resource_not_found():
 
 ✅ **State transition tests:** Tests that verify how resources change state between API operations.
 
-```python order_transition_test.py
+```python filename="order_transition_test.py"
 def test_order_transition_from_pending_to_processing():
     # Create order
     order = client.orders.create({"items": [{"product_id": "123", "quantity": 1}]})
@@ -345,7 +347,7 @@ def test_order_transition_from_pending_to_processing():
 
 ✅ **Complex business logic validation:** Tests that verify domain-specific rules and constraints.
 
-```python discount_test.py
+```python filename="discount_test.py"
 def test_discount_applied_only_to_eligible_items():
     # Create cart with mixed eligible and non-eligible items
     cart = client.carts.create({

docs/create-terraform.mdx

@@ -89,7 +89,8 @@ Speakeasy helps you autogenerate documentation using the HashiCorp `terraform-pl
 
 The Swagger Petstore generates a usage snippet for the pet resource similar to the following:
 
-```go "petstore_pet" "my_pet" {
+```go 
+"petstore_pet" "my_pet" {
     id   = 10
     name = "doggie"
     photo_urls = [
@@ -158,7 +159,7 @@ Speakeasy natively supports the direct import of resources with multiple ID fiel
 
 An import block allows you to import a resource into the Terraform state by generating the corresponding Terraform configuration. Using a composite key, the import block will look like this:
 
-```hcl test.tf
+```hcl filename="test.tf"
 import {
   id = jsonencode({
     primary_key_one: "9cedad30-2a8a-40f7-9d65-4fabb04e54ff"

docs/customize/code/code-regions/java.mdx

@@ -8,7 +8,7 @@ description: "Learn how to use custom code regions in Java SDKs."
 To enable custom code regions for Java SDKs, update the project's
 `.speakeasy/gen.yaml` file as follows:
 
-```diff .speakeasy/gen.yaml
+```diff filename=".speakeasy/gen.yaml"
 configVersion: 2.0.0
 generation:
   # ...
@@ -51,7 +51,7 @@ Java model classes can also have custom code regions:
 
 When adding custom code that requires external packages, configure these dependencies in the `.speakeasy/gen.yaml` file to prevent them from being removed during SDK regeneration. Use the `additionalDependencies` configuration to specify package dependencies:
 
-```yaml .speakeasy/gen.yaml
+```yaml filename=".speakeasy/gen.yaml"
 java:
   additionalDependencies:
     - implementation:org.commonmark:commonmark:0.21.0
@@ -62,7 +62,7 @@ java:
 
 This ensures that dependencies persist across SDK regenerations and are properly included in the generated `build.gradle`.
 
-```java src/main/java/com/example/sdk/Todos.java
+```java filename="src/main/java/com/example/sdk/Todos.java"
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */
@@ -115,7 +115,7 @@ public class Todos implements
 
 You can also add custom methods to model classes. This example adds a `render()` method to a `Todo` model class:
 
-```java src/main/java/com/example/sdk/models/components/Todo.java
+```java filename="src/main/java/com/example/sdk/models/components/Todo.java"
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */

docs/customize/code/code-regions/python.mdx

@@ -8,7 +8,7 @@ description: "Learn how to use custom code regions in Python SDKs."
 To enable custom code regions for Python SDKs, update the project's
 `.speakeasy/gen.yaml` file as follows:
 
-```diff .speakeasy/gen.yaml
+```diff filename=".speakeasy/gen.yaml"
 configVersion: 2.0.0
 generation:
   # ...
@@ -40,7 +40,7 @@ Python SDK classes can have two code regions:
 
 When adding custom code that requires external packages, configure these dependencies in the `.speakeasy/gen.yaml` file to prevent them from being removed during SDK regeneration. Use the `additionalDependencies` configuration to specify package dependencies:
 
-```yaml .speakeasy/gen.yaml
+```yaml filename=".speakeasy/gen.yaml"
 python:
   additionalDependencies:
     main:
@@ -53,7 +53,7 @@ python:
 
 This ensures that dependencies persist across SDK regenerations and are properly included in the generated `pyproject.toml`.
 
-```python src/todos_sdk/todos.py
+```python filename="src/todos_sdk/todos.py"
 """Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""
 
 from .basesdk import BaseSDK

docs/customize/code/code-regions/typescript.mdx

@@ -8,7 +8,7 @@ description: "Learn how to use custom code regions in TypeScript SDKs."
 To enable custom code regions for TypeScript SDKs, update the project's
 `.speakeasy/gen.yaml` file as follows:
 
-```diff .speakeasy/gen.yaml
+```diff filename=".speakeasy/gen.yaml"
 configVersion: 2.0.0
 generation:
   # ...
@@ -40,7 +40,7 @@ TypeScript SDK classes can have two code regions:
 
 When adding custom code that requires external packages, configure these dependencies in the `.speakeasy/gen.yaml` file to prevent them from being removed during SDK regeneration. Use the `additionalDependencies` configuration to specify package dependencies:
 
-```yaml .speakeasy/gen.yaml
+```yaml filename=".speakeasy/gen.yaml"
 typescript:
   additionalDependencies:
     dependencies:
@@ -54,7 +54,7 @@ typescript:
 
 This ensures that dependencies persist across SDK regenerations and are properly included in the generated `package.json`.
 
-```typescript src/sdk/todos.ts
+```typescript filename="src/sdk/todos.ts"
 /*
  * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
  */

docs/customize/data-model/additionalproperties.mdx

@@ -19,7 +19,7 @@ Speakeasy sets `additionalProperties` to `false` by default unless explicitly de
 
 Set `additionalProperties: true` to accept arbitrary fields beyond the defined properties. This is useful for accepting unpredictable fields or allowing future extensions without schema updates.
 
-```yaml openapi.yaml
+```yaml filename="openapi.yaml"
 components:
   schemas:
     FlexibleObject:
@@ -58,7 +58,7 @@ await sdk.items.create({
 
 Constrain additional properties to a specific type:
 
-```yaml openapi.yaml
+```yaml filename="openapi.yaml" 
 components:
   schemas:
     StringOnlyObject:

docs/customize/structure/imports.mdx

@@ -179,7 +179,7 @@ You can customize these paths to any path that exists relative to the root of th
 
 Different buckets can also be configured to use the same path, for example:
 
-```yaml gen.yaml
+```yaml filename="gen.yaml"
 typescript:
   ...
   imports:

docs/customize/structure/namespaces.mdx

@@ -18,7 +18,7 @@ Each method will then be added to namespaces corresponding with its `tags`. If a
 
 The following example illustrates the method `sdk.Drinks.ListDrinks()` assigned to the `Drinks` namespace and another method `sdk.ListLocations()` kept in the default class:
 
-```yaml Tags
+```yaml filename="Tags"
 paths:
   /bar_locations:
     get:
@@ -70,7 +70,7 @@ Sometimes the `tags` in an OpenAPI spec may already be used for an unrelated pur
 
 The `x-speakeasy-group` field allows defining custom namespaces. Add this field to any operation in the OpenAPI spec to override any `tags` associated with that method. For example:
 
-```yaml x-speakeasy-group
+```yaml filename="x-speakeasy-group"
 paths:
   /drinks/{drink_type}/get_vintage:
     get: