Skip to content

Show request body examples in docs - #30

Open
kafkasl wants to merge 1 commit into
mainfrom
body-examples
Open

Show request body examples in docs#30
kafkasl wants to merge 1 commit into
mainfrom
body-examples

Conversation

@kafkasl

@kafkasl kafkasl commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

An OpenAPI request body can carry examples in two places:

  1. Whole-payload examples, sitting next to the schema: named sample request bodies under examples (or the OpenAPI 3.0 singular example).
  2. Per-parameter examples, sitting inside the schema: sample values attached to individual properties.

Runpod's POST /v2/pods, the case that prompted this PR, has both. Next to the schema:

content:
  application/json:
    schema:
      $ref: "#/components/schemas/CreatePodRequest"
    examples:
      gpuPod:
        summary: GPU pod
        value:
          name: pytorch-training
          image: runpod/pytorch:1.0.2-cu1281-torch280-ubuntu2404
          gpu:
            id: NVIDIA GeForce RTX 4090
            count: 1
          disk: 50

And inside CreatePodRequest:

name:
  type: string
  minLength: 1
  examples:
  - my-training-pod

We drop both kinds. This is made worse by the fact we only parse the top level of the schema. A nested object param comes out typed as bare dict, and everything beneath it is discarded. For example the doc() on this op shows:

- gpu (dict, optional): GPU request for a pod create. Carries the CUDA host constraints, which live here rather than at the body's top level so they are unrepresentable on a CPU pod.

The caller can't construct a valid body without going back to the raw spec.

I decided to improve this by adding the 1. Whole-payload examples into the docs. It is a concise fix and displaying the main payload examples should mitigate the issue in most happy-paths.

Nothing changes when a spec has no examples.

@kafkasl kafkasl self-assigned this Aug 26, 2026
@kafkasl kafkasl changed the title added body examples to doc Show request body examples in docs Aug 26, 2026
@kafkasl
kafkasl marked this pull request as draft August 26, 2026 13:40
@kafkasl kafkasl added the enhancement New feature or request label Aug 26, 2026
@kafkasl
kafkasl marked this pull request as ready for review August 26, 2026 13:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant