Code Samples

Overview

When you connect an OpenAPI specification, HolyDocs automatically generates code samples for every API endpoint. These samples update dynamically as readers fill in parameters in the playground, providing copy-ready code in their preferred language.

Supported Languages

HolyDocs generates code samples in 7 languages:

Example Output

For a POST /api/v1/users endpoint with a JSON body, HolyDocs generates:

bash
curl -X POST https://api.yourcompany.com/api/v1/users \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Jane Doe",    "email": "jane@example.com",    "role": "admin"  }'

javascript
const response = await fetch('https://api.yourcompany.com/api/v1/users', {  method: 'POST',  headers: {    'Authorization': 'Bearer YOUR_API_KEY',    'Content-Type': 'application/json',  },  body: JSON.stringify({    name: 'Jane Doe',    email: 'jane@example.com',    role: 'admin',  }),});const data = await response.json();console.log(data);

python
import requestsresponse = requests.post(    'https://api.yourcompany.com/api/v1/users',    headers={        'Authorization': 'Bearer YOUR_API_KEY',        'Content-Type': 'application/json',    },    json={        'name': 'Jane Doe',        'email': 'jane@example.com',        'role': 'admin',    },)data = response.json()print(data)

go
package mainimport (    "bytes"    "encoding/json"    "fmt"    "net/http"    "io")func main() {    body, _ := json.Marshal(map[string]string{        "name":  "Jane Doe",        "email": "jane@example.com",        "role":  "admin",    })    req, _ := http.NewRequest("POST",        "https://api.yourcompany.com/api/v1/users",        bytes.NewBuffer(body))    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")    req.Header.Set("Content-Type", "application/json")    resp, _ := http.DefaultClient.Do(req)    defer resp.Body.Close()    data, _ := io.ReadAll(resp.Body)    fmt.Println(string(data))}

Configuration

Selecting Languages

Choose which languages to display in code samples:

json
{  "api": {    "examples": {      "languages": ["javascript", "python", "curl", "go"]    }  }}

If not specified, all 7 languages are shown. The reader's language preference is persisted across pages.

Pre-fill Behavior

Control whether example values from your OpenAPI spec are pre-filled in code samples:

json
{  "api": {    "examples": {      "prefill": true,      "defaults": "required"    }  }}

• prefill: true — Fills parameters with example values from the spec
• defaults: "required" — Only pre-fills required parameters
• defaults: "all" — Pre-fills all parameters including optional ones

Dynamic Updates

When a reader modifies parameter values in the API playground, the code samples update in real-time to reflect the actual values they entered. This ensures the code they copy is ready to use without modification.

Custom Code Samples

For endpoints that need custom code examples (e.g., multi-step workflows or SDK usage), you can provide custom samples in your MDX:

mdx
---title: Upload Fileopenapi: "POST /api/v1/files"---## SDK ExampleThe recommended approach is to use the official SDK:```javascriptimport { HolyDocs } from '@holydocs/sdk';const client = new HolyDocs({ apiKey: 'YOUR_API_KEY' });const file = await client.files.upload({  path: './document.pdf',  metadata: { category: 'reports' },});console.log(file.url);

Custom code samples are displayed alongside the auto-generated ones.

Auto-generated code samples pull example values from your OpenAPI spec's example and examples fields. Adding good examples to your spec improves the quality of generated code.