Writing Parameter Descriptions — Complete Guide

In this tutorial, you will learn about Writing Parameter Descriptions. We cover key concepts, practical examples, and best practices to help you master this topic.

Parameter descriptions document every input an API endpoint accepts with the parameter name, data type, format, whether it is required, default value, constraints like minimum and maximum, and a realistic example that shows the correct formatting for each value.

What You'll Learn

How to write clear parameter descriptions that prevent integration errors, what information every parameter needs, how to document constraints and validation rules, how to describe parameter relationships and conditional requirements, and how to format parameter tables for scannability.

Why It Matters

Parameters are where most API integration bugs originate. A developer sends the wrong type, forgets a required field, or uses an incorrect format. Clear parameter descriptions with examples prevent these errors and reduce debugging time.

Real-World Use

The DodaTech API parameter documentation includes type, format, required status, default, constraints, and example for every parameter. When the team added example values to every parameter description, parameter-related support tickets dropped by 60 percent.

Parameter Table Format

flowchart TD
  A[Parameter Table] --> B[Name]
  A --> C[Type]
  A --> D[Required]
  A --> E[Default]
  A --> F[Description]
  F --> G[What it does]
  F --> H[Constraints]
  F --> I[Example]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Writing Parameter Descriptions

Every parameter in the table needs a description that tells the developer what the parameter does, any constraints, and what format the value should take.

#### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `page` | integer | No | 1 | Page number for pagination. Minimum 1. Example: 3 |
| `per_page` | integer | No | 20 | Items per page. Minimum 1, maximum 100. Example: 50 |
| `sort` | string | No | `created_at` | Sort field for results. Values: `created_at` (default), `name`, `size`. Example: `name` |
| `order` | string | No | `desc` | Sort direction. Values: `asc` (ascending), `desc` (descending). Example: `asc` |
| `status` | string | No | `all` | Filter files by status. Values: `active`, `archived`, `deleted`. Example: `active` |

## Describing Constraints

Be explicit about every constraint on the parameter value.

```markdown
#### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fileId` | string | Yes | Unique file identifier. Must match pattern: `file_` followed by 16 lowercase alphanumeric characters. Example: `file_a1b2c3d4e5f6g7h8` |

#### Body Parameters

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `format` | string | No | `zip` | Compression format. Must be one of: `zip` (ZIP archive, widest compatibility), `gzip` (single-file GZIP, best for text/logs), `sevenz` (7-Zip LZMA2, best compression ratio). Example: `gzip` |
| `level` | integer | No | 6 | Compression level. Range 1-9. Higher values produce smaller files but take longer. Level 9 is ~15% smaller than level 1 but takes 3x longer. Example: 9 |
| `password` | string | No | — | AES-256 encryption password. Must be 8-64 characters. Example: `my-secure-password-123` |

## Conditional Parameters

Some parameters are conditionally required based on other parameter values.

```markdown
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `file_url` | string (uri) | Conditional | Public URL of the file. Required if `file` is not provided. Example: `https://example.com/report.pdf` |
| `file` | binary | Conditional | Direct file upload. Required if `file_url` is not provided. Use multipart/form-data content type. |

**Note:** Provide exactly one of `file_url` or `file`. If both are provided, `file` takes precedence.

## Parameter Examples in Descriptions

Include example values directly in the description column for extra clarity.

```markdown
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | No | Search query for filtering files by name. Searches both name and extension. Example: `?q=report` matches "Annual Report.pdf" and "report_card.csv" |
| `date_from` | string (date) | No | Filter files created on or after this date. Format: YYYY-MM-DD. Example: `2026-01-01` |
| `date_to` | string (date) | No | Filter files created on or before this date. Format: YYYY-MM-DD. Example: `2026-12-31` |

## Enumerated Values

For enum parameters, list all valid values and their meanings.

```markdown
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `format` | string | No | `zip` | Compression format. Supported values: `zip` (standard ZIP, fastest, widest compatibility), `gzip` (single-file GZIP, best for text/log files), `sevenz` (7-Zip LZMA2, best compression ratio, slowest). Example: `zip` |

## Common Mistakes

### 1. Missing Type Information

Parameters without type documentation cause type errors in strongly-typed languages. Always document the expected data type.

### 2. No Example Values

Parameters without examples force developers to guess the format. Show realistic example values.

### 3. Vague Descriptions

Writing The page number without explaining what the page is for, what the minimum is, or what happens when omitted.

### 4. Missing Constraints

Not documenting minimum, maximum, pattern, or enum values causes validation errors that could be prevented.

### 5. No Default Documentation

Optional parameters without documented defaults lead developers to assume defaults that may not be correct.

### 6. Unclear Conditional Requirements

Conditionally required parameters without clear conditions. State exactly when each parameter is required.

### 7. Inconsistent Format

Some parameters with examples, some without. Some with type in the description, some with type in the column. Follow a consistent format.

## Practice Questions

**1. What information should every parameter description include?**

Name, type, required status, default value, constraints (min/max/pattern/enum), description of what it does, and a realistic example.

**2. How do you document conditionally required parameters?**

Mark them as Conditional in the Required column and explain the condition in the description: Required if file_url is not provided.

**3. What is the best way to document enum parameters?**

List all valid values with brief explanations of when to use each one. Show the default value first or mark it explicitly.

**4. Why include examples in parameter descriptions?**

Examples help developers understand the expected format without reading a separate example section. Good examples prevent format-related integration errors.

**5. Challenge:** Write parameter descriptions for an endpoint that has at least 8 parameters including path, query, header, body, conditional, enum, and constrained numeric parameters.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should every parameter have an example?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Yes. Examples are essential for preventing format-related errors. Even simple parameters benefit from examples showing the expected format.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How do I document parameters with complex validation rules?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>State the rules in the description using plain language: Must be 8-64 characters, Must match pattern, Must be one of these values. Simple rules are better than formal validation language.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">What if a parameter has no default value?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Mark the default as — or Required and explain what happens if the parameter is omitted: If not provided, the API returns 400 Bad Request.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How do I document deprecated parameters?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Mark them as Deprecated in the description, show the deprecation version, and provide the replacement parameter name and sunset date.</p>
</div></details>

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Where do parameter descriptions come from?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>The OpenAPI spec defines parameter properties. The writer enhances these with plain-language descriptions, realistic examples, and usage guidance that the spec alone cannot provide.</p>
</div></details>

## Mini Project: Parameter Description Audit

Find an API endpoint with poorly documented parameters. Rewrite the parameter documentation for all parameters including type, required status, default, constraints, clear descriptions, and realistic examples. Also document any conditional requirements or parameter interactions.

## What's Next

Parameters define the inputs. Now learn to document the data developers send with Request Body Examples. Then explore Response Examples for documenting API outputs.