Skip to content

Improve swagger documentation with response objects and status-codes #182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 2, 2025
Merged

Improve swagger documentation with response objects and status-codes #182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1123608
Improve swagger documentation with response objects and status-codes
imretoth-ess May 27, 2025
46116ee
Fix review comments
imretoth-ess May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 171 additions & 1 deletion src/main/java/org/phoebus/channelfinder/ChannelManager.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

import com.google.common.collect.FluentIterable;
import com.google.common.collect.Lists;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.phoebus.channelfinder.AuthorizationService.ROLES;
import org.phoebus.channelfinder.entity.Channel;
import org.phoebus.channelfinder.entity.Property;
Expand Down Expand Up @@ -72,6 +77,22 @@ public class ChannelManager {
* @param allRequestParams query parameters
* @return list of all channels
*/
@ApiResponses(
Copy link
Contributor

@anderslindho anderslindho May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should add @Operation annotations here and elsewhere

Copy link
Contributor

@anderslindho anderslindho May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

value = {
@ApiResponse(
responseCode = "200",
description = "List of channels",
content = @Content(
array = @ArraySchema(schema = @Schema(implementation = Channel.class)))),
@ApiResponse(
responseCode = "400",
description = "Invalid request",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to find all channels",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@GetMapping
public List<Channel> query(@RequestParam MultiValueMap<String, String> allRequestParams) {
return channelRepository.search(allRequestParams).channels();
Expand All @@ -85,18 +106,45 @@ public List<Channel> query(@RequestParam MultiValueMap<String, String> allReques
* @param allRequestParams query parameters
* @return SearchResult a count to the total number of matches and the first 10k hits
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "The number of matches for the query, and the first 10k channels",
content = @Content(
array = @ArraySchema(schema = @Schema(implementation = SearchResult.class)))),
Copy link
Contributor

@anderslindho anderslindho May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, doesn't this return a SearchResult object?

Copy link
Contributor Author

@imretoth-ess imretoth-ess May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@anderslindho anderslindho May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jacomago thoughts?

@ApiResponse(
responseCode = "400",
description = "Invalid request - response size exceeded",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to find all channels",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@GetMapping("/combined")
public SearchResult combinedQuery(@RequestParam MultiValueMap<String, String> allRequestParams) {
return channelRepository.search(allRequestParams);
}

/**
* GET method for quering the number of matches to a multi-parameter query specifying patterns for tags, property values, and
* GET method for querying the number of matches to a multi-parameter query specifying patterns for tags, property values, and
* channel names to match against.
*
* @param allRequestParams query parameters
* @return a total number of channels that match the query parameters
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "The number of channels matching the query",
content = @Content(schema = @Schema(implementation = Long.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to count the result for channel-query",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@GetMapping("/count")
public long queryCount(@RequestParam MultiValueMap<String, String> allRequestParams) {
return channelRepository.count(allRequestParams);
Expand All @@ -109,6 +157,17 @@ public long queryCount(@RequestParam MultiValueMap<String, String> allRequestPar
* @param channelName - channel name to search for
* @return found channel
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "Channel with the specified name",
content = @Content(schema = @Schema(implementation = Channel.class))),
@ApiResponse(
responseCode = "404",
description = "Channel not found",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@GetMapping("/{channelName}")
public Channel read(@PathVariable("channelName") String channelName) {
channelManagerAudit.log(Level.INFO, () -> MessageFormat.format(TextUtil.FIND_CHANNEL, channelName));
Expand All @@ -132,6 +191,29 @@ public Channel read(@PathVariable("channelName") String channelName) {
* @param channel - new data (properties/tags) for channel <code>chan</code>
* @return the created channel
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "The created/replaced channel",
content = @Content(schema = @Schema(implementation = Channel.class))),
@ApiResponse(
responseCode = "400",
description = "Invalid request",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "401",
description = "Unauthorized",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "404",
description = "Channel, Tag, or property not found",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to create channel",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@PutMapping("/{channelName}")
public Channel create(@PathVariable("channelName") String channelName, @RequestBody Channel channel) {
// check if authorized role
Expand Down Expand Up @@ -172,6 +254,30 @@ public Channel create(@PathVariable("channelName") String channelName, @RequestB
* @param channels - XmlChannels to be created
Copy link
Contributor

@anderslindho anderslindho May 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically out of scope for your PR but this isn't right - both XmlChannels and "to be created" (as it's PUT)

* @return the list of channels created
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "The created/replaced channels",
content = @Content(
array = @ArraySchema(schema = @Schema(implementation = Channel.class)))),
@ApiResponse(
responseCode = "400",
description = "Invalid request",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "401",
description = "Unauthorized",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "404",
description = "Tag, or property not found",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to create channels",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@PutMapping
public Iterable<Channel> create(@RequestBody Iterable<Channel> channels) {
// check if authorized role
Expand Down Expand Up @@ -249,6 +355,29 @@ private void resetOwnersToExisting(Iterable<Channel> channels) {
* @param channel - new Channel data (properties/tags) to be merged into channel <code>channelName</code>
* @return the updated channel
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "The updated channel",
content = @Content(schema = @Schema(implementation = Channel.class))),
@ApiResponse(
responseCode = "400",
description = "Invalid request",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "401",
description = "Unauthorized",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "404",
description = "Channel, Tag, or property not found",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to update channel",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@PostMapping("/{channelName}")
public Channel update(@PathVariable("channelName") String channelName, @RequestBody Channel channel) {
if(authorizationService.isAuthorizedRole(SecurityContextHolder.getContext().getAuthentication(), ROLES.CF_CHANNEL)) {
Expand Down Expand Up @@ -305,6 +434,29 @@ public Channel update(@PathVariable("channelName") String channelName, @RequestB
* @param channels - XmlChannels to be updated
* @return the updated channels
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "The updated channels",
content = @Content(schema = @Schema(implementation = Channel.class))),
@ApiResponse(
responseCode = "400",
description = "Invalid request",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "401",
description = "Unauthorized",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "404",
description = "Channel not found",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to update channels",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@PostMapping()
public Iterable<Channel> update(@RequestBody Iterable<Channel> channels) {
// check if authorized role
Expand Down Expand Up @@ -351,6 +503,24 @@ public Iterable<Channel> update(@RequestBody Iterable<Channel> channels) {
*
* @param channelName - name of channel to remove
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "Channel deleted"),
@ApiResponse(
responseCode = "401",
description = "Unauthorized",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "404",
description = "Channel not found",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to delete channel",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@DeleteMapping("/{channelName}")
public void remove(@PathVariable("channelName") String channelName) {
// check if authorized role
Expand Down
26 changes: 26 additions & 0 deletions src/main/java/org/phoebus/channelfinder/ChannelScroll.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

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

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import java.text.MessageFormat;
import java.util.Comparator;
import java.util.List;
Expand Down Expand Up @@ -58,6 +62,17 @@ public class ChannelScroll {
* @param allRequestParams search parameters
* @return list of all channels
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "Scroll that contains a collection of channel instances",
content = @Content(schema = @Schema(implementation = Scroll.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to list channels",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@GetMapping
public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams) {
return search(null, allRequestParams);
Expand All @@ -71,6 +86,17 @@ public Scroll query(@RequestParam MultiValueMap<String, String> allRequestParams
* @param scrollId scroll Id
* @return list of all channels
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "Scroll List of channels",
content = @Content(schema = @Schema(implementation = Scroll.class))),
@ApiResponse(
responseCode = "500",
description = "Error while trying to list channels",
content = @Content(schema = @Schema(implementation = ResponseStatusException.class)))
})
@GetMapping("/{scrollId}")
public Scroll query(@PathVariable("scrollId") String scrollId, @RequestParam MultiValueMap<String, String> searchParameters) {
return search(scrollId, searchParameters);
Expand Down
10 changes: 10 additions & 0 deletions src/main/java/org/phoebus/channelfinder/InfoManager.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

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

import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import java.io.IOException;
import java.util.LinkedHashMap;
import java.util.Map;
Expand Down Expand Up @@ -41,6 +45,12 @@ public class InfoManager {
*
* @return Information about the ChannelFinder service
*/
@ApiResponses(
value = {
@ApiResponse(
responseCode = "200",
description = "ChannelFinder info", content = @Content(schema = @Schema(implementation = String.class)))
})
@GetMapping
public String info() {

Expand Down
Loading