ePages-de / ePages-de/restdocs-api-spec

Document array of string/enum?

Open
#146 4 comments 5 reactions 0 assignees View on GitHub
bug
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.