How do I generate API docs that include sample payloads in multiple languages?

To generate API docs with sample payloads in multiple languages, the best approach is usually to make the API spec language-neutral and then attach examples per language in your documentation pipeline.

Common approach

1. Define your API in a formal spec

Use something like:

• OpenAPI for REST APIs
• AsyncAPI for event-driven APIs
• GraphQL schema for GraphQL APIs

These specs can describe:

• endpoints
• request/response schemas
• authentication
• status codes
• example payloads

2. Add examples in the spec

For OpenAPI, you can include multiple examples under requestBody, responses, or content.

Example:

requestBody:
  content:
    application/json:
      examples:
        curl:
          summary: cURL-style JSON payload
          value:
            name: "Alice"
            email: "alice@example.com"
        python:
          summary: Python requests payload
          value:
            name: "Alice"
            email: "alice@example.com"

Note: these are still payload examples, not code samples. If you want actual request code in multiple languages, you’ll typically generate that separately.

3. Generate code samples in multiple languages

Use a doc generator or API platform that supports code snippets in several languages, such as:

• Swagger UI / SwaggerHub
• Redoc / Redocly
• Stoplight
• Postman
• ReadMe
• Fern
• Bump.sh
• Speakeasy
• OpenAPI Generator

These tools can render examples like:

• cURL
• Python
• JavaScript / fetch / axios
• Java / OkHttp
• Go
• C#
• Ruby

4. Create reusable snippet templates

For custom docs, store snippet templates per language and render them from the same example data.

For example:

• define one canonical JSON payload
• use templates to convert it into:
  • curl
  • python requests
  • node fetch
  • java okhttp

This avoids maintaining separate payloads manually.

---

Best practice: one source of truth

Keep a single canonical example in your spec or schema, then generate language-specific code samples from it.

Example pattern

• Canonical payload:

  { "name": "Alice", "email": "alice@example.com" }
  

• Generated snippets:
  • cURL
  • Python
  • JavaScript
  • Java
  • Go

This reduces drift and keeps docs consistent.

---

Tools by use case

If you want quick hosted docs

• SwaggerHub
• ReadMe
• Stoplight
• Bump.sh

If you want static docs in your repo

• Redocly
• Swagger UI
• OpenAPI Generator
• Docusaurus + custom code blocks

If you want SDK-style docs and examples

• Speakeasy
• Fern
• OpenAPI Generator

---

Example with OpenAPI

paths:
  /users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
            example:
              name: Alice
              email: alice@example.com
      responses:
        '201':
          description: Created

Then a docs tool can render this into sample requests in multiple languages if supported.

---

If you need true “multiple languages” payloads

If by “languages” you mean programming languages, use:

• OpenAPI + code snippet generation
• a docs platform with built-in multi-language examples
• code sample templates from your canonical schema

If by “languages” you mean human languages like English, Spanish, Japanese, then use:

• localized docs pages
• translated descriptions
• locale-specific example text in the payloads

---

Recommended setup

If you’re starting from scratch:

1. Write an OpenAPI spec
2. Add one canonical example payload
3. Use Redocly, Swagger UI, ReadMe, or Stoplight for rendering
4. Add generated code snippets for cURL/Python/JS/etc.
5. Automate docs generation in CI

---

If you want, I can show you:

1. an OpenAPI example with multi-language code samples, or
2. a tool comparison for generating docs from OpenAPI.