Skip to content

Commit bcc1b4d

Browse files
jacomagojacomago
authored
Merge pull request #182 from ChannelFinder/Improve_swagger_documentation
Improve swagger documentation with response objects and status-codes
2 parents 7e53182 + 46116ee commit bcc1b4d

File tree

6 files changed

+604
-1
lines changed

6 files changed

+604
-1
lines changed

‎src/main/java/org/phoebus/channelfinder/ChannelManager.java‎

Lines changed: 171 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
import com.google.common.collect.FluentIterable;
44
import com.google.common.collect.Lists;
5+
import io.swagger.v3.oas.annotations.media.ArraySchema;
6+
import io.swagger.v3.oas.annotations.media.Content;
7+
import io.swagger.v3.oas.annotations.media.Schema;
8+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
9+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
510
import org.phoebus.channelfinder.AuthorizationService.ROLES;
611
import org.phoebus.channelfinder.entity.Channel;
712
import org.phoebus.channelfinder.entity.Property;
@@ -72,6 +77,22 @@ public class ChannelManager {
7277
* @param allRequestParams query parameters
7378
* @return list of all channels
7479
*/
80+
@ApiResponses(
81+
value = {
82+
@ApiResponse(
83+
responseCode = "200",
84+
description = "List of channels",
85+
content = @Content(
86+
array = @ArraySchema(schema = @Schema(implementation = Channel.class)))),
87+
@ApiResponse(
88+
responseCode = "400",
89+
description = "Invalid request",
90+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
91+
@ApiResponse(
92+
responseCode = "500",
93+
description = "Error while trying to find all channels",
94+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
95+
})
7596
@GetMapping
7697
public List<Channel> query(@RequestParam MultiValueMap<String, String> allRequestParams) {
7798
return channelRepository.search(allRequestParams).channels();
@@ -85,18 +106,45 @@ public List<Channel> query(@RequestParam MultiValueMap<String, String> allReques
85106
* @param allRequestParams query parameters
86107
* @return SearchResult a count to the total number of matches and the first 10k hits
87108
*/
109+
@ApiResponses(
110+
value = {
111+
@ApiResponse(
112+
responseCode = "200",
113+
description = "The number of matches for the query, and the first 10k channels",
114+
content = @Content(
115+
array = @ArraySchema(schema = @Schema(implementation = SearchResult.class)))),
116+
@ApiResponse(
117+
responseCode = "400",
118+
description = "Invalid request - response size exceeded",
119+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
120+
@ApiResponse(
121+
responseCode = "500",
122+
description = "Error while trying to find all channels",
123+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
124+
})
88125
@GetMapping("/combined")
89126
public SearchResult combinedQuery(@RequestParam MultiValueMap<String, String> allRequestParams) {
90127
return channelRepository.search(allRequestParams);
91128
}
92129

93130
/**
94-
* GET method for quering the number of matches to a multi-parameter query specifying patterns for tags, property values, and
131+
* GET method for querying the number of matches to a multi-parameter query specifying patterns for tags, property values, and
95132
* channel names to match against.
96133
*
97134
* @param allRequestParams query parameters
98135
* @return a total number of channels that match the query parameters
99136
*/
137+
@ApiResponses(
138+
value = {
139+
@ApiResponse(
140+
responseCode = "200",
141+
description = "The number of channels matching the query",
142+
content = @Content(schema = @Schema(implementation = Long.class))),
143+
@ApiResponse(
144+
responseCode = "500",
145+
description = "Error while trying to count the result for channel-query",
146+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
147+
})
100148
@GetMapping("/count")
101149
public long queryCount(@RequestParam MultiValueMap<String, String> allRequestParams) {
102150
return channelRepository.count(allRequestParams);
@@ -109,6 +157,17 @@ public long queryCount(@RequestParam MultiValueMap<String, String> allRequestPar
109157
* @param channelName - channel name to search for
110158
* @return found channel
111159
*/
160+
@ApiResponses(
161+
value = {
162+
@ApiResponse(
163+
responseCode = "200",
164+
description = "Channel with the specified name",
165+
content = @Content(schema = @Schema(implementation = Channel.class))),
166+
@ApiResponse(
167+
responseCode = "404",
168+
description = "Channel not found",
169+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
170+
})
112171
@GetMapping("/{channelName}")
113172
public Channel read(@PathVariable("channelName") String channelName) {
114173
channelManagerAudit.log(Level.INFO, () -> MessageFormat.format(TextUtil.FIND_CHANNEL, channelName));
@@ -132,6 +191,29 @@ public Channel read(@PathVariable("channelName") String channelName) {
132191
* @param channel - new data (properties/tags) for channel <code>chan</code>
133192
* @return the created channel
134193
*/
194+
@ApiResponses(
195+
value = {
196+
@ApiResponse(
197+
responseCode = "200",
198+
description = "The created/replaced channel",
199+
content = @Content(schema = @Schema(implementation = Channel.class))),
200+
@ApiResponse(
201+
responseCode = "400",
202+
description = "Invalid request",
203+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
204+
@ApiResponse(
205+
responseCode = "401",
206+
description = "Unauthorized",
207+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
208+
@ApiResponse(
209+
responseCode = "404",
210+
description = "Channel, Tag, or property not found",
211+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
212+
@ApiResponse(
213+
responseCode = "500",
214+
description = "Error while trying to create channel",
215+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
216+
})
135217
@PutMapping("/{channelName}")
136218
public Channel create(@PathVariable("channelName") String channelName, @RequestBody Channel channel) {
137219
// check if authorized role
@@ -172,6 +254,30 @@ public Channel create(@PathVariable("channelName") String channelName, @RequestB
172254
* @param channels - XmlChannels to be created
173255
* @return the list of channels created
174256
*/
257+
@ApiResponses(
258+
value = {
259+
@ApiResponse(
260+
responseCode = "200",
261+
description = "The created/replaced channels",
262+
content = @Content(
263+
array = @ArraySchema(schema = @Schema(implementation = Channel.class)))),
264+
@ApiResponse(
265+
responseCode = "400",
266+
description = "Invalid request",
267+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
268+
@ApiResponse(
269+
responseCode = "401",
270+
description = "Unauthorized",
271+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
272+
@ApiResponse(
273+
responseCode = "404",
274+
description = "Tag, or property not found",
275+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
276+
@ApiResponse(
277+
responseCode = "500",
278+
description = "Error while trying to create channels",
279+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
280+
})
175281
@PutMapping
176282
public Iterable<Channel> create(@RequestBody Iterable<Channel> channels) {
177283
// check if authorized role
@@ -249,6 +355,29 @@ private void resetOwnersToExisting(Iterable<Channel> channels) {
249355
* @param channel - new Channel data (properties/tags) to be merged into channel <code>channelName</code>
250356
* @return the updated channel
251357
*/
358+
@ApiResponses(
359+
value = {
360+
@ApiResponse(
361+
responseCode = "200",
362+
description = "The updated channel",
363+
content = @Content(schema = @Schema(implementation = Channel.class))),
364+
@ApiResponse(
365+
responseCode = "400",
366+
description = "Invalid request",
367+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
368+
@ApiResponse(
369+
responseCode = "401",
370+
description = "Unauthorized",
371+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
372+
@ApiResponse(
373+
responseCode = "404",
374+
description = "Channel, Tag, or property not found",
375+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
376+
@ApiResponse(
377+
responseCode = "500",
378+
description = "Error while trying to update channel",
379+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
380+
})
252381
@PostMapping("/{channelName}")
253382
public Channel update(@PathVariable("channelName") String channelName, @RequestBody Channel channel) {
254383
if(authorizationService.isAuthorizedRole(SecurityContextHolder.getContext().getAuthentication(), ROLES.CF_CHANNEL)) {
@@ -305,6 +434,29 @@ public Channel update(@PathVariable("channelName") String channelName, @RequestB
305434
* @param channels - XmlChannels to be updated
306435
* @return the updated channels
307436
*/
437+
@ApiResponses(
438+
value = {
439+
@ApiResponse(
440+
responseCode = "200",
441+
description = "The updated channels",
442+
content = @Content(schema = @Schema(implementation = Channel.class))),
443+
@ApiResponse(
444+
responseCode = "400",
445+
description = "Invalid request",
446+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
447+
@ApiResponse(
448+
responseCode = "401",
449+
description = "Unauthorized",
450+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
451+
@ApiResponse(
452+
responseCode = "404",
453+
description = "Channel not found",
454+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
455+
@ApiResponse(
456+
responseCode = "500",
457+
description = "Error while trying to update channels",
458+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
459+
})
308460
@PostMapping()
309461
public Iterable<Channel> update(@RequestBody Iterable<Channel> channels) {
310462
// check if authorized role
@@ -351,6 +503,24 @@ public Iterable<Channel> update(@RequestBody Iterable<Channel> channels) {
351503
*
352504
* @param channelName - name of channel to remove
353505
*/
506+
@ApiResponses(
507+
value = {
508+
@ApiResponse(
509+
responseCode = "200",
510+
description = "Channel deleted"),
511+
@ApiResponse(
512+
responseCode = "401",
513+
description = "Unauthorized",
514+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
515+
@ApiResponse(
516+
responseCode = "404",
517+
description = "Channel not found",
518+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
519+
@ApiResponse(
520+
responseCode = "500",
521+
description = "Error while trying to delete channel",
522+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
523+
})
354524
@DeleteMapping("/{channelName}")
355525
public void remove(@PathVariable("channelName") String channelName) {
356526
// check if authorized role

‎src/main/java/org/phoebus/channelfinder/ChannelScroll.java‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
import static org.phoebus.channelfinder.CFResourceDescriptors.SCROLL_RESOURCE_URI;
44

5+
import io.swagger.v3.oas.annotations.media.Content;
6+
import io.swagger.v3.oas.annotations.media.Schema;
7+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
8+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
59
import java.text.MessageFormat;
610
import java.util.Comparator;
711
import java.util.List;
@@ -58,6 +62,17 @@ public class ChannelScroll {
5862
* @param allRequestParams search parameters
5963
* @return list of all channels
6064
*/
65+
@ApiResponses(
66+
value = {
67+
@ApiResponse(
68+
responseCode = "200",
69+
description = "Scroll that contains a collection of channel instances",
70+
content = @Content(schema = @Schema(implementation = Scroll.class))),
71+
@ApiResponse(
72+
responseCode = "500",
73+
description = "Error while trying to list channels",
74+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
75+
})
6176
@GetMapping
6277
public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams) {
6378
return search(null, allRequestParams);
@@ -71,6 +86,17 @@ public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams
7186
* @param scrollId scroll Id
7287
* @return list of all channels
7388
*/
89+
@ApiResponses(
90+
value = {
91+
@ApiResponse(
92+
responseCode = "200",
93+
description = "Scroll List of channels",
94+
content = @Content(schema = @Schema(implementation = Scroll.class))),
95+
@ApiResponse(
96+
responseCode = "500",
97+
description = "Error while trying to list channels",
98+
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
99+
})
74100
@GetMapping("/{scrollId}")
75101
public Scroll query(@PathVariable("scrollId") String scrollId, @RequestParam MultiValueMap<String, String> searchParameters) {
76102
return search(scrollId, searchParameters);

‎src/main/java/org/phoebus/channelfinder/InfoManager.java‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
import static org.phoebus.channelfinder.CFResourceDescriptors.CF_SERVICE_INFO;
44

5+
import io.swagger.v3.oas.annotations.media.Content;
6+
import io.swagger.v3.oas.annotations.media.Schema;
7+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
8+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
59
import java.io.IOException;
610
import java.util.LinkedHashMap;
711
import java.util.Map;
@@ -41,6 +45,12 @@ public class InfoManager {
4145
*
4246
* @return Information about the ChannelFinder service
4347
*/
48+
@ApiResponses(
49+
value = {
50+
@ApiResponse(
51+
responseCode = "200",
52+
description = "ChannelFinder info", content = @Content(schema = @Schema(implementation = String.class)))
53+
})
4454
@GetMapping
4555
public String info() {
4656

0 commit comments

Comments
 (0)