SwaggerHub中OpenAPI 3.0 API响应显示[null]而非示例值求助

I’ve run into this exact issue before with SwaggerHub not rendering example responses correctly (showing [null] instead of expected sample values). Let’s walk through the most common fixes tailored to your /customers/get_customers endpoint:

1. Verify Your example/examples Configuration in the Response Schema #

SwaggerHub relies on properly structured example or examples fields to render sample responses. For an array of customers, double-check your schema setup:

Single Example (Using example) #

Make sure you define the example at both the array level and item level (if needed):

responses:
  '200':
    description: Successful retrieval of customer list
    content:
      application/json:
        schema:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              first_name:
                type: string
              last_name:
                type: string
            # Example for a single customer object
            example:
              id: 1
              first_name: "Chris"
              last_name: "Muench"
          # Example for the full array of customers
          example:
            - id: 1
              first_name: "Chris"
              last_name: "Muench"
            - id: 2
              first_name: "Jane"
              last_name: "Doe"

Multiple Examples (Using examples) #

If you’re using the plural examples field, follow the OpenAPI 3.0 structure with summary and value:

content:
  application/json:
    examples:
      SampleCustomerList:
        summary: A sample list of 2 customers
        value:
          - id: 1
            first_name: "Chris"
            last_name: "Muench"
          - id: 2
            first_name: "Jane"
            last_name: "Doe"

2. Check SwaggerHub’s Rendering Settings #

Sometimes SwaggerHub might default to using schema defaults instead of examples. Head to the Settings (top-right corner of the editor) and ensure the "Use Examples" option is enabled. This forces the UI to prioritize your defined examples over generic placeholder values.

3. Validate Schema Type Matching #

If your example values don’t match the schema’s defined types (e.g., a string for an integer field, or a single object instead of an array), SwaggerHub will fail to render the example and fall back to [null]. Do a quick audit:

• Confirm the root schema for the response is type: array
• Ensure all nested field examples match their declared types (e.g., id is a number, not a string)

4. Fix Any Syntax/Validation Errors in Your OpenAPI Definition #

Even small syntax issues (like incorrect indentation, missing commas, or invalid schema keywords) can break example rendering. Use SwaggerHub’s built-in Validate tool (left sidebar) to scan your entire definition for errors. Fix any reported issues, then refresh the preview to see if the examples appear correctly.

内容的提问来源于stack exchange，提问作者Chris Muench