How to format json for api documentation and readme examples
- Step 1Collect the request and response samples — Copy the raw JSON from your API testing tool (Postman, Insomnia, curl output). These are often compact or inconsistently indented.
- Step 2Prettify with documentation-appropriate indent — Use 2-space indent for inline documentation examples and 4-space indent for standalone example files or README code blocks. Choose based on your documentation style guide.
- Step 3Add to documentation as a fenced code block — Wrap the prettified JSON in a Markdown code block: ```json\n{\n \"key\": \"value\"\n}\n```. The syntax highlighting renders the JSON with key/value coloring in GitHub, Docusaurus, and most documentation platforms.
- Step 4For OpenAPI: add as example in the spec — Add the formatted JSON as an example value in the OpenAPI spec under responses.[200].content.application/json.examples.success.value. OpenAPI renders this example in Swagger UI and Redoc documentation.
Frequently asked questions
Should I use real or synthetic data in API documentation examples?+
Use synthetic data that is realistic but does not contain real customer information. Create fictional names, email addresses, and IDs that clearly look like examples ([email protected], user_id: 12345). Never include real customer data in documentation — it is a GDPR violation and a security risk.
How do I include JSON examples in OpenAPI specs written in YAML?+
In YAML, format the JSON as a YAML string with | for multi-line string format, then parse it as a string value. Alternatively, use native YAML syntax — YAML is a superset of JSON, so you can paste prettified JSON directly into an OpenAPI YAML file and it will parse correctly.
Is the API sample data transmitted to JAD Apps?+
No. Formatting runs entirely in your browser. API sample payloads and documentation examples are never transmitted to JAD Apps servers.
Privacy first
Conversion runs locally in your browser. No file is uploaded — only metadata counters are saved for signed-in dashboard stats.