Skip to content

Commit 574cd0c

Browse files
e-pettersson-ericssone-pettersson-ericsson
authored
Improve swagger documentation (#426)
- Align description on endpoints in Swagger GUI - Add clarification on subscription endpoint with single subscriptions - Update version - Update subscription API docs for 3.0.0
1 parent c01402b commit 574cd0c

11 files changed

+63
-65
lines changed

‎pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<modelVersion>4.0.0</modelVersion>
77
<groupId>com.github.ericsson</groupId>
88
<artifactId>eiffel-intelligence</artifactId>
9-
<version>3.0.0</version>
9+
<version>3.0.1-SNAPSHOT</version>
1010
<packaging>war</packaging>
1111

1212
<parent>

‎src/main/java/com/ericsson/ei/controller/AggregatedObjectControllerImpl.java

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,15 +37,14 @@
3737
import com.ericsson.ei.utils.ResponseMessage;
3838
import com.fasterxml.jackson.databind.ObjectMapper;
3939

40-
import io.swagger.annotations.Api;
4140
import io.swagger.annotations.ApiOperation;
4241

4342
/**
44-
* This class represents the REST GET mechanism to extract the aggregated data on the basis of the ID from the aggregatedObject.
43+
* This class represents the REST GET mechanism to extract the aggregated data on the basis of the
44+
* Id from the aggregatedObject.
4545
*/
4646
@Component
4747
@CrossOrigin
48-
@Api(value = "aggregatedObject", tags = { "aggregated object" })
4948
public class AggregatedObjectControllerImpl implements AggregatedObjectController {
5049

5150
private static final Logger LOGGER = LoggerFactory.getLogger(AggregatedObjectControllerImpl.class);
@@ -57,13 +56,14 @@ public class AggregatedObjectControllerImpl implements AggregatedObjectControlle
5756
private ProcessQueryParams processQueryParams;
5857

5958
/**
60-
* This method is responsible for the REST Get mechanism to extract the aggregated data on the basis of the ID from the aggregatedObject.
59+
* This method is responsible for the REST Get mechanism to extract the aggregated data on the
60+
* basis of the Id from the aggregatedObject.
6161
*
6262
* @param id
6363
* @return ResponseEntity
6464
*/
6565
@Override
66-
@ApiOperation(value = "")
66+
@ApiOperation(value = "Get a specific aggregated object", tags = { "Aggregated objects" })
6767
public ResponseEntity<?> getAggregatedObjectById(@PathVariable final String id,
6868
final HttpServletRequest httpRequest) {
6969
ObjectMapper mapper = new ObjectMapper();
@@ -90,7 +90,7 @@ public ResponseEntity<?> getAggregatedObjectById(@PathVariable final String id,
9090

9191
@Override
9292
@CrossOrigin
93-
@ApiOperation(value = "Perform a freestyle query to retrieve aggregated objects")
93+
@ApiOperation(value = "Perform a freestyle query to retrieve aggregated objects", tags = { "Aggregated objects" })
9494
public ResponseEntity<?> createAggregatedObjectsQuery(@RequestBody final QueryBody body,
9595
final HttpServletRequest httpRequest) {
9696
String emptyResponseContent = "[]";

‎src/main/java/com/ericsson/ei/controller/AuthenticationControllerImpl.java

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,6 @@
3030

3131
import com.ericsson.ei.utils.ResponseMessage;
3232

33-
import io.swagger.annotations.Api;
3433
import io.swagger.annotations.ApiOperation;
3534

3635
/**
@@ -39,7 +38,6 @@
3938
*/
4039
@Component
4140
@CrossOrigin
42-
@Api(value = "Auth", tags = { "Authentication" })
4341
public class AuthenticationControllerImpl implements AuthenticationController {
4442

4543
private static final Logger LOGGER = LoggerFactory.getLogger(AuthenticationControllerImpl.class);
@@ -49,7 +47,8 @@ public class AuthenticationControllerImpl implements AuthenticationController {
4947

5048
@Override
5149
@CrossOrigin
52-
@ApiOperation(value = "To check if security is enabled", response = String.class)
50+
@ApiOperation(value = "Check if security is enabled", tags = { "Authentication" },
51+
response = String.class)
5352
public ResponseEntity<?> getAuthentication(final HttpServletRequest httpRequest) {
5453
try {
5554
return new ResponseEntity<>(new JSONObject().put("security", ldapEnabled).toString(),
@@ -64,7 +63,8 @@ public ResponseEntity<?> getAuthentication(final HttpServletRequest httpRequest)
6463

6564
@Override
6665
@CrossOrigin
67-
@ApiOperation(value = "To get login of current user", response = String.class)
66+
@ApiOperation(value = "Get login of current user", tags = { "Authentication" }, response =
67+
String.class)
6868
public ResponseEntity<?> getAuthenticationLogin(final HttpServletRequest httpRequest) {
6969
try {
7070
String currentUser = SecurityContextHolder.getContext().getAuthentication().getName();

‎src/main/java/com/ericsson/ei/controller/FailedNotificationControllerImpl.java

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -33,15 +33,13 @@
3333
import com.ericsson.ei.queryservice.ProcessFailedNotification;
3434
import com.ericsson.ei.utils.ResponseMessage;
3535

36-
import io.swagger.annotations.Api;
3736
import io.swagger.annotations.ApiOperation;
3837

3938
/**
4039
* This class contains logic for retrieving failed notifications for the given subscription.
4140
*/
4241
@Component
4342
@CrossOrigin
44-
@Api(value = "failedNotifications", tags = { "Failed notifications" })
4543
public class FailedNotificationControllerImpl implements FailedNotificationController {
4644

4745
private final static Logger LOGGER = LoggerFactory.getLogger(
@@ -54,10 +52,11 @@ public class FailedNotificationControllerImpl implements FailedNotificationContr
5452
* This method is responsible for the REST GET mechanism to extract the data on the basis of the
5553
* subscription name from the Failed Notification Object.
5654
*
57-
* @param subscriptionName
55+
* @param subscriptionNames
5856
*/
5957
@Override
60-
@ApiOperation(value = "Retrieve failed notifications", response = QueryResponse.class)
58+
@ApiOperation(value = "Retrieve failed notifications", tags = { "Failed notifications" },
59+
response = QueryResponse.class)
6160
public ResponseEntity<?> getFailedNotifications(
6261
@RequestParam(value = "subscriptionNames", required = true) final String subscriptionNames,
6362
final HttpServletRequest httpRequest) {
@@ -70,7 +69,7 @@ public ResponseEntity<?> getFailedNotifications(
7069
String errorMessage = "Failed to fetch failed notifications for subscription(s): " + subscriptionNames;
7170
LOGGER.error(errorMessage, e);
7271
String errorJsonAsString = ResponseMessage.createJsonMessage(errorMessage);
73-
return new ResponseEntity<>(errorJsonAsString, HttpStatus.INTERNAL_SERVER_ERROR);
72+
return new ResponseEntity<>(errorJsonAsString, HttpStatus.INTERNAL_SERVER_ERROR);
7473
}
7574
}
7675

‎src/main/java/com/ericsson/ei/controller/InformationControllerImpl.java

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@
1616
import com.ericsson.ei.controller.model.ParseInstanceInfoEI;
1717
import com.ericsson.ei.utils.ResponseMessage;
1818
import com.fasterxml.jackson.databind.ObjectMapper;
19-
import io.swagger.annotations.Api;
2019
import io.swagger.annotations.ApiOperation;
2120

2221
import javax.servlet.http.HttpServletRequest;
@@ -31,7 +30,6 @@
3130

3231
@Component
3332
@CrossOrigin
34-
@Api(value = "information", tags = {"Information"})
3533
public class InformationControllerImpl implements InformationController {
3634
private static final Logger LOGGER = LoggerFactory.getLogger(InformationControllerImpl.class);
3735

@@ -40,7 +38,8 @@ public class InformationControllerImpl implements InformationController {
4038

4139
@Override
4240
@CrossOrigin
43-
@ApiOperation(value = "Shows information about Eiffel Intelligence backend")
41+
@ApiOperation(value = "Shows information about Eiffel Intelligence back-end", tags = {
42+
"Information"})
4443
public ResponseEntity<?> getInformation(final HttpServletRequest httpRequest) {
4544
try {
4645
String info = new ObjectMapper().writerWithDefaultPrettyPrinter().writeValueAsString(instanceInfo);

‎src/main/java/com/ericsson/ei/controller/RuleControllerImpl.java

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,10 @@
3434
import com.fasterxml.jackson.databind.JsonNode;
3535
import com.fasterxml.jackson.databind.ObjectMapper;
3636

37-
import io.swagger.annotations.Api;
3837
import io.swagger.annotations.ApiOperation;
3938

4039
@Component
4140
@CrossOrigin
42-
@Api(value = "Rules", tags = {"Rules"})
4341
public class RuleControllerImpl implements RuleController{
4442

4543
private static final Logger LOGGER = LoggerFactory.getLogger(RuleControllerImpl.class);
@@ -52,7 +50,8 @@ public class RuleControllerImpl implements RuleController{
5250

5351
@Override
5452
@CrossOrigin
55-
@ApiOperation(value = "Get the active rules from Eiffel Intelligence", response = String.class)
53+
@ApiOperation(value = "Get the active rules from Eiffel Intelligence", tags = {"Rules"},
54+
response = String.class)
5655
public ResponseEntity<?> getRules(final HttpServletRequest httpRequest) {
5756
JsonNode rulesContent = rulesHandler.getRulesContent();
5857
ObjectMapper objectmapper = new ObjectMapper();

‎src/main/java/com/ericsson/ei/controller/RuleTestControllerImpl.java

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,12 @@
2323
import com.ericsson.ei.services.IRuleCheckService;
2424
import com.ericsson.ei.utils.ResponseMessage;
2525

26-
import io.swagger.annotations.Api;
2726
import io.swagger.annotations.ApiOperation;
2827
import io.swagger.annotations.ApiParam;
2928
import lombok.Setter;
3029

3130
@Component
3231
@CrossOrigin
33-
@Api(value = "Rule test", tags = {"Templates"})
3432
public class RuleTestControllerImpl implements RuleTestController {
3533
private static final Logger LOGGER = LoggerFactory.getLogger(RuleTestControllerImpl.class);
3634

@@ -60,7 +58,8 @@ public class RuleTestControllerImpl implements RuleTestController {
6058
*/
6159
@Override
6260
@CrossOrigin
63-
@ApiOperation(value = "To execute rule on one Eiffel event", response = String.class)
61+
@ApiOperation(value = "Execute rule on one Eiffel event", tags = {"Rule-test"}, response
62+
= String.class)
6463
public ResponseEntity<?> createRuleTestRunSingleRule (
6564
@ApiParam(value = "JSON object", required = true) @RequestBody RuleCheckBody body, final HttpServletRequest httpRequest) {
6665
JSONObject rule = new JSONObject(body.getRule().getAdditionalProperties());
@@ -81,7 +80,8 @@ public ResponseEntity<?> createRuleTestRunSingleRule (
8180

8281
@Override
8382
@CrossOrigin
84-
@ApiOperation(value = "To execute the list of rules on list of Eiffel events. Returns the aggregated object(s)", response = String.class)
83+
@ApiOperation(value = "Execute a list of rules on a list of Eiffel events. Returns the "
84+
+ "aggregated object(s)", tags = {"Rule-test"}, response = String.class)
8585
public ResponseEntity<?> createRuleTestRunFullAggregation(
8686
@ApiParam(value = "Object that include list of rules and list of Eiffel events", required = true) @RequestBody RulesCheckBody body,
8787
final HttpServletRequest httpRequest) {
@@ -114,7 +114,8 @@ public ResponseEntity<?> createRuleTestRunFullAggregation(
114114
}
115115

116116
@Override
117-
@ApiOperation(value = "Check if rules check service is enabled", response = String.class)
117+
@ApiOperation(value = "Check if rules test service is enabled", tags = {"Rule-test"},
118+
response = String.class)
118119
public ResponseEntity<?> getRuleTest(HttpServletRequest httpRequest) {
119120
LOGGER.debug("Getting Enabling Status of Rules Check Service");
120121
try {

‎src/main/java/com/ericsson/ei/controller/StatusControllerImpl.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ public class StatusControllerImpl implements StatusController {
5050

5151
@Override
5252
@CrossOrigin
53-
@ApiOperation(value = "To check back-end status", response = String.class)
53+
@ApiOperation(value = "Check back-end status", tags = { "Status" }, response = String.class)
5454
public ResponseEntity<?> getStatus(HttpServletRequest httpRequest) {
5555
try {
5656
final JsonNode status = statusHandler.getCurrentStatus();

‎src/main/java/com/ericsson/ei/controller/SubscriptionControllerImpl.java

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,6 @@
5353

5454
@Component
5555
@CrossOrigin
56-
@Api(value = "subscriptions", tags = {"Subscriptions"})
5756
public class SubscriptionControllerImpl implements SubscriptionController {
5857

5958
private static final Logger LOGGER = LoggerFactory.getLogger(SubscriptionControllerImpl.class);
@@ -70,7 +69,7 @@ public class SubscriptionControllerImpl implements SubscriptionController {
7069

7170
@Override
7271
@CrossOrigin
73-
@ApiOperation(value = "Creates subscription(s)")
72+
@ApiOperation(value = "Create subscription(s)", tags = {"Subscriptions"})
7473
public ResponseEntity<?> createSubscription(@RequestBody List<Subscription> subscriptions, final HttpServletRequest httpRequest) {
7574
Map<String, String> errorMap = new HashMap<>();
7675
String user = (ldapEnabled) ? HttpSessionConfig.getCurrentUser() : "";
@@ -100,7 +99,7 @@ public ResponseEntity<?> createSubscription(@RequestBody List<Subscription> subs
10099

101100
@Override
102101
@CrossOrigin
103-
@ApiOperation(value = "Updates existing subscription(s)")
102+
@ApiOperation(value = "Update existing subscription(s)", tags = {"Subscriptions"})
104103
public ResponseEntity<?> updateSubscriptions(@RequestBody List<Subscription> subscriptions, final HttpServletRequest httpRequest) {
105104
Map<String, String> errorMap = new HashMap<>();
106105
String user = (ldapEnabled) ? HttpSessionConfig.getCurrentUser() : "";
@@ -129,7 +128,7 @@ public ResponseEntity<?> updateSubscriptions(@RequestBody List<Subscription> sub
129128

130129
@Override
131130
@CrossOrigin
132-
@ApiOperation(value = "Retrieves all or specific subscriptions")
131+
@ApiOperation(value = "Retrieve all or specific subscriptions", tags = {"Subscriptions"})
133132
public ResponseEntity<?> getSubscriptions(@RequestParam(required = false) String subscriptionNames,
134133
final HttpServletRequest httpRequest) {
135134
String queryString = httpRequest.getQueryString();
@@ -150,21 +149,21 @@ public ResponseEntity<?> getSubscriptions(@RequestParam(required = false) String
150149

151150
@Override
152151
@CrossOrigin
153-
@ApiOperation(value = "Retrieve a subscription")
152+
@ApiOperation(value = "Retrieve a single subscription", tags = {"Subscriptions"})
154153
public ResponseEntity<?> getSubscriptionByName(@PathVariable String subscriptionName, final HttpServletRequest httpRequest) {
155154
return getSingleSubscription(subscriptionName);
156155
}
157156

158157
@Override
159158
@CrossOrigin
160-
@ApiOperation(value = "Remove subscription(s)")
159+
@ApiOperation(value = "Remove subscription(s)", tags = {"Subscriptions"})
161160
public ResponseEntity<?> deleteSubscriptions(@RequestParam String subscriptionNames, final HttpServletRequest httpRequest) {
162161
return deleteListedSubscriptions(subscriptionNames);
163162
}
164163

165164
@Override
166165
@CrossOrigin
167-
@ApiOperation(value = "Remove a subscription")
166+
@ApiOperation(value = "Remove a single subscription", tags = {"Subscriptions"})
168167
public ResponseEntity<?> deleteSubscriptionByName(@PathVariable String subscriptionName, final HttpServletRequest httpRequest) {
169168
return deleteSingleSubscription(subscriptionName);
170169
}

‎src/main/java/com/ericsson/ei/controller/TemplateControllerImpl.java

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,18 +32,15 @@
3232

3333
import com.ericsson.ei.utils.ResponseMessage;
3434

35-
import io.swagger.annotations.Api;
36-
3735
@Component
3836
@CrossOrigin
39-
@Api(value = "Get templates", tags = {"Templates"})
4037
public class TemplateControllerImpl implements TemplateController {
4138

4239
private static final Logger LOGGER = LoggerFactory.getLogger(
4340
TemplateControllerImpl.class);
4441

4542
@Override
46-
@ApiOperation(value = "Retrieve REST endpoints for downloading templates")
43+
@ApiOperation(value = "Retrieve REST endpoints for downloading templates", tags = {"Templates"})
4744
public ResponseEntity<?> getTemplates(final HttpServletRequest httpRequest) {
4845
try {
4946
JSONObject response = new JSONObject();
@@ -60,7 +57,7 @@ public ResponseEntity<?> getTemplates(final HttpServletRequest httpRequest) {
6057
}
6158

6259
@Override
63-
@ApiOperation(value = "Download subscription template")
60+
@ApiOperation(value = "Download subscription template", tags = {"Templates"})
6461
public ResponseEntity<?> getTemplatesSubscriptions(final HttpServletRequest httpRequest) {
6562
try {
6663
InputStream is = getClass().getResourceAsStream(
@@ -80,7 +77,7 @@ public ResponseEntity<?> getTemplatesSubscriptions(final HttpServletRequest http
8077
}
8178

8279
@Override
83-
@ApiOperation(value = "Download rules template")
80+
@ApiOperation(value = "Download rules template", tags = {"Templates"})
8481
public ResponseEntity<?> getTemplatesRules(final HttpServletRequest httpRequest) {
8582
try {
8683
InputStream is = getClass().getResourceAsStream(
@@ -100,7 +97,7 @@ public ResponseEntity<?> getTemplatesRules(final HttpServletRequest httpRequest)
10097
}
10198

10299
@Override
103-
@ApiOperation(value = "Download Eiffel events template")
100+
@ApiOperation(value = "Download Eiffel events template", tags = {"Templates"})
104101
public ResponseEntity<?> getTemplatesEvents(final HttpServletRequest httpRequest) {
105102
try {
106103
InputStream is = getClass().getResourceAsStream(

0 commit comments

Comments
 (0)