Improve swagger documentation with response objects and status-codes #182
Conversation
|
Is it possible to replace all the MultiValueMap with more specific list of query params? Most of them I think are for the search and it should be possible to have query params like: ~size |
|
Well, yes and no. Another thing I just noticed that if the RequestBody is an Iterable type, it is not showing up on swagger. I think it can not decide what structure it should show/parse, since List, Map,... have different structure. |
imretoth-ess
requested review from
anderslindho,
domonkos-ess,
jacomago and
simon-ess
anderslindho
left a comment
anderslindho
left a comment
There was a problem hiding this comment.
Largely looks good to me, but some nitpicks here and there.
@jacomago I don't think we will want to create a release with annotating the operations... Should we create follow-up or handle here? It might 2x the PR and work.
| * @param allRequestParams query parameters | ||
| * @return list of all channels | ||
| */ | ||
| @ApiResponses( |
There was a problem hiding this comment.
I think we should add @Operation annotations here and elsewhere
There was a problem hiding this comment.
You can ignore this part @imretoth-ess - I will create a sub-task and I can take that myself so you don't have to modify the scope in the middle of the PR
| responseCode = "200", | ||
| description = "The number of matches for the query, and the first 10k channels", | ||
| content = @Content( | ||
| array = @ArraySchema(schema = @Schema(implementation = SearchResult.class)))), |
There was a problem hiding this comment.
Hmm, doesn't this return a SearchResult object?
There was a problem hiding this comment.
Yes, it responds with a SearchResult object that contains only 2 fields: a count, and a List of Channels - but on the response List length there is a restriction
| /** | ||
| * PUT method for creating multiple channels. | ||
| * | ||
| * @param channels - XmlChannels to be created |
There was a problem hiding this comment.
Technically out of scope for your PR but this isn't right - both XmlChannels and "to be created" (as it's PUT)
|
|
|
LGTM |
Extended swagger documentation for the REST interface with response objects and status-codes