ePages-de / ePages-de/restdocs-api-spec
Document array of string/enum?
- Dominant language
- Kotlin
- Stars
- 427
- Forks
- 116
- Avg merge
- 23h 54m
- Merged PRs (30d)
- 1
Description
By using this library to document my rest API I struggled to document an array of enums. My model contains a list of simple Enums.
Model:
```java
private List state =
Lists.newArrayList(
StateValue.SUCCESS,
StateValue.ERROR,
StateValue.WARNING);
```
By describing my model with the following line
```java
fieldWithPath("state").type(JsonFieldType.ARRAY).description("array of states")
```
i got this as result:
```yaml
state:
type: array
description: array of states
items:
oneOf:
- type: object
- type: boolean
- type: string
- type: number
```
The expected result should be like
```json
"state" : {
"type" : "array",
"description" : "array of states",
"items" : {
"type": "string",
"enum": [
"SUCCESS",
"ERROR",
"WARNING"
]
}
},
```
I looked at the implementation of this plugin and tried to find a workaround for this problem. By describing the "state" field in my model with the type of "Enum" I got at least the enum documented in the right way.
```java
fieldWithPath("state")
.type("ENUM")
.description("array of states")
.attributes(key("enumValues").value(List.of(StateValue.values())))));
```
Result:
```json
"state" : {
"type" : "string",
"description" : "Array of journey states",
"enum" : [ "SUCCESS", "ERROR", "WARNING" ]
},
```
I found a similar issue here #87 which is marked as fixed but it did not work.
Is there a way to document an array of enums correctly in regards to openApi3 specifications? Is there a way to fix this issue in time?
I also want to mention that the documentation about document enums could be improved. Nothing was found about it in the library documentation. Only looking at the implementation I was able to document a simple Enum.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.