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

Open
#287 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.