ePages-de / ePages-de/restdocs-api-spec
requestFields example is not reflected as requestBody example, so Swagger UI "Edit Value" does not show the expected example
- Dominant language
- Kotlin
- Stars
- 427
- Forks
- 116
- Avg merge
- 23h 54m
- Merged PRs (30d)
- 1
Description
### 1. Problem Summary
- When I use `.attributes(key("example").value(...))` in `requestFields(...)` to specify an example for each field,
the OpenAPI 3 output only includes the example at the schema/properties/field level.
- The OpenAPI `requestBody` does **not** get an overall `example` (singular) generated automatically.
- As a result, the Swagger UI "Edit Value" tab does **not** show the expected example JSON by default.
---
### 2. Expected Behavior
- I expect that the field examples from `requestFields` would be combined and used to generate a top-level `example` in the OpenAPI `requestBody`, like this:
```json
"requestBody": {
"content": {
"application/json": {
"schema": { ... },
"example": { "targetDate": "yyyy-MM-dd" }
}
}
}
```
- The Swagger UI "Edit Value" tab should then automatically show:
```json
{ "targetDate": "yyyy-MM-dd" }
```
---
### 3. Actual Behavior
- Each field’s example is present in the OpenAPI schema/properties,
but there is **no** top-level `example` in the `requestBody`.
- The Swagger UI "Edit Value" tab is empty or just shows `{}` by default.
---
### 4. Minimal Reproducible Example
```java
.requestFields(
fieldWithPath("targetDate").type(JsonFieldType.STRING)
.description("Settlement base date (e.g., 2025-06-23)")
.attributes(key("example").value("yyyy-MM-dd"))
)
```
---
### 5. Environment
- restdocs-api-spec version: (e.g., 0.19.4)
- Spring REST Docs version: (e.g., 3.x)
- Swagger UI version: (e.g., 4.x)
- JDK: (e.g., 17)
---
### 6. Additional Notes
- As a workaround, I can post-process the generated openapi3.json to add the top-level `example`, but it would be great if this was supported natively.
---
Thank you!
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.