[backend] Adding swagger documentation on Tags and TagRules endpoints #2257
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## improvment/add-team-api-doc #2257 +/- ##
=================================================================
+ Coverage 32.77% 32.79% +0.01%
Complexity 1500 1500
=================================================================
Files 580 579 -1
Lines 17938 17931 -7
Branches 1169 1169
=================================================================
Hits 5880 5880
+ Misses 11794 11787 -7
Partials 264 264 ☔ View full report in Codecov by Sentry. |
openbas-api/src/main/java/io/openbas/rest/tag_rule/form/TagRuleOutput.java
Outdated
Show resolved
Hide resolved
| @@ -26,6 +31,10 @@ | |||
| import org.springframework.web.bind.annotation.*; | |||
|
|
|||
| @RestController | |||
| @io.swagger.v3.oas.annotations.tags.Tag( | |||
There was a problem hiding this comment.
question: tags in @operation create new sections in the swagger. According to the doc, the behavior for this @tag should be the same. Is that the case and if yes, is that what we want?
| value = { | ||
| @ApiResponse( | ||
| responseCode = "200", | ||
| description = "All the existing corresponding to the search criteria") |
There was a problem hiding this comment.
All the existing -> All the existing tags
| @@ -26,6 +31,10 @@ | |||
| import org.springframework.web.bind.annotation.*; | |||
|
|
|||
| @RestController | |||
| @io.swagger.v3.oas.annotations.tags.Tag( | |||
| name = "Tags management", | |||
| description = "Endpoints to manage tags") | |||
There was a problem hiding this comment.
Maybe we should describe here what tags are or put a link to the public doc as well ?
| @@ -72,6 +96,8 @@ public Tag createTag(@Valid @RequestBody TagCreateInput input) { | |||
| @Secured(ROLE_ADMIN) | |||
| @PostMapping("/api/tags/upsert") | |||
| @Transactional(rollbackOn = Exception.class) | |||
| @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "The created tag")}) | |||
There was a problem hiding this comment.
"the created tag" => "the upserted tag" ?
| @@ -85,15 +111,23 @@ public Tag upsertTag(@Valid @RequestBody TagCreateInput input) { | |||
|
|
|||
| @Secured(ROLE_ADMIN) | |||
| @DeleteMapping("/api/tags/{tagId}") | |||
| public void deleteTag(@PathVariable String tagId) { | |||
| @ApiResponses(value = {@ApiResponse(responseCode = "200")}) | |||
There was a problem hiding this comment.
If we return void, should this be a 204 ?
| @Operation(summary = "Get TagRule by Id") | ||
| public TagRuleOutput findTagRule(@PathVariable @NotBlank final String tagRuleId) { | ||
| @Operation(description = "Get TagRule by Id", summary = "Get TagRule") | ||
| @ApiResponses(value = {@ApiResponse(responseCode = "200", description = "The tag rule")}) |
There was a problem hiding this comment.
Sometime, we talk about TagRule and other "tag rule". Should we uniformize this?
| @@ -58,7 +70,8 @@ public List<TagRuleOutput> tags() { | |||
| @ApiResponse(responseCode = "200", description = "TagRule deleted"), | |||
| @Valid @RequestBody final TagRuleInput input) { | ||
| return tagRuleMapper.toTagRuleOutput( | ||
| tagRuleService.updateTagRule(tagRuleId, input.getTagName(), input.getAssetGroups())); | ||
| } | ||
|
|
||
| @LogExecutionTime | ||
| @PostMapping(TagRuleApi.TAG_RULE_URI + "/search") | ||
| @Operation(summary = "Search TagRule") | ||
| @Operation( | ||
| description = "Search TagRule corresponding to search criteria", |
| @Operation(summary = "Search TagRule") | ||
| @Operation( | ||
| description = "Search TagRule corresponding to search criteria", | ||
| summary = "Search TagRule") |
| @@ -18,8 +19,10 @@ | |||
| public class TagRuleInput { | |||
| @NotBlank(message = MANDATORY_MESSAGE) | |||
| @JsonProperty("tag_name") | |||
| @Schema(description = "Name of the tag rule") | |||
There was a problem hiding this comment.
Name of the tag rule or name of the tag ? (variable name vs doc is misleading, I think)
Proposed changes
Related issues
Checklist
Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...