Summary
When using the following parameter declaration in Grape:
optional :dns_servers, type: [String], desc: 'DNS servers', allow_blank: false, default: ["8.8.8.8", "8.8.4.4"]
grape-swagger generates an OpenAPI schema where the default value is incorrectly placed inside items, instead of being set at the array level. This causes the field to be interpreted as a nested array ([[value]]) in Swagger tools and breaks the expected structure.
🔍 Current Behavior (Incorrect)
Generated OpenAPI snippet:
dns_servers:
type: array
items:
type: string
default: ["8.8.8.8", "8.8.4.4"] # ❌ incorrect placement — default on items must be a single value, not an array⚠️ Swagger Editor interprets this as:
"dns_servers": [
["8.8.8.8", "8.8.4.4"]
]
Which is not the intended behavior, and breaks compatibility with clients, documentation, and tools.
✅ Expected Behavior
The correct OpenAPI output should look like this:
dns_servers:
type: array
items:
type: string
default:
- "8.8.8.8"
- "8.8.4.4"This correctly documents a default array of strings, not a nested array of arrays.
🧪 Minimal Reproducible Example (Swagger Editor — OpenAPI 2.0 - https://editor.swagger.io)
swagger: "2.0"
info:
title: DNS Servers Example
version: "1.0"
paths:
/example:
post:
parameters:
- in: body
name: postV1Organization
required: true
schema:
type: object
properties:
dns_servers:
type: array
items:
type: string
default: ["8.8.8.8", "8.8.4.4"] # ❌ incorrect — invalid type, causes nested array
responses:
200:
description: OK✅ Correct version for comparison:
dns_servers:
type: array
items:
type: string
default:
- "8.8.8.8"
- "8.8.4.4"
📚 Specification Insights (OpenAPI & JSON Schema)
🔎 Why this matters
- Placing
default inside items implies a per-item default, which is not meaningful for array parameters.
- Putting an array value as the
default inside items (which expects a scalar) leads to nested arrays and invalid schemas.
- This issue causes confusion in docs, misbehavior in tools, and breaks conformity with OpenAPI semantics.
🔗 Related
📦 Version Info
ruby: 3.3.4grape: 2.3.0grape-swagger: 2.1.2
💡 Suggestion: when generating schemas from type: [String] with a default, grape-swagger should ensure the default is set at the array level — not inside items, and that its type conforms to OpenAPI expectations.
Summary
When using the following parameter declaration in Grape:
grape-swaggergenerates an OpenAPI schema where thedefaultvalue is incorrectly placed insideitems, instead of being set at the array level. This causes the field to be interpreted as a nested array ([[value]]) in Swagger tools and breaks the expected structure.🔍 Current Behavior (Incorrect)
Generated OpenAPI snippet:
Which is not the intended behavior, and breaks compatibility with clients, documentation, and tools.
✅ Expected Behavior
The correct OpenAPI output should look like this:
This correctly documents a default array of strings, not a nested array of arrays.
🧪 Minimal Reproducible Example (Swagger Editor — OpenAPI 2.0 - https://editor.swagger.io)
✅ Correct version for comparison:
📚 Specification Insights (OpenAPI & JSON Schema)
OpenAPI 3.0 Schema Object:
Swagger 2.0 Items Object:
JSON Schema - enum:
JSON Schema - default:
🔎 Why this matters
defaultinsideitemsimplies a per-item default, which is not meaningful for array parameters.defaultinsideitems(which expects a scalar) leads to nested arrays and invalid schemas.🔗 Related
📦 Version Info
ruby:3.3.4grape:2.3.0grape-swagger:2.1.2💡 Suggestion: when generating schemas from
type: [String]with adefault,grape-swaggershould ensure thedefaultis set at the array level — not insideitems, and that its type conforms to OpenAPI expectations.