Add OpenAPI annotation examples

modules/external-api/pom.xml

@@ -32,6 +32,10 @@
       <groupId>org.osgi</groupId>
       <artifactId>org.osgi.service.jaxrs</artifactId>
     </dependency>
+    <dependency>
+      <groupId>io.swagger.core.v3</groupId>
+      <artifactId>swagger-annotations</artifactId>
+    </dependency>
     <!-- opencast -->
     <dependency>
       <groupId>org.opencastproject</groupId>
@@ -268,11 +272,6 @@
               javax.ws.rs.core;version=2.0.1,
               *
             </Import-Package>
-            <Private-Package>
-              org.opencastproject.external.exception,
-              org.opencastproject.external.util,
-              org.opencastproject.external.util.statistics
-            </Private-Package>
             <Export-Package>
               org.opencastproject.external.api,
               org.opencastproject.external.common,

modules/external-api/src/main/java/org/opencastproject/external/common/ApiResponses.java → modules/external-api/src/main/java/org/opencastproject/external/common/ApiResponseBuilder.java

@@ -34,11 +34,11 @@
 /**
  * A utility class for creating responses from the external api.
  */
-public final class ApiResponses {
+public final class ApiResponseBuilder {
 
   private static final String APPLICATION_PREFIX = "application/";
 
-  private ApiResponses() {
+  private ApiResponseBuilder() {
 
   }
 

modules/external-api/src/main/java/org/opencastproject/external/endpoint/BaseEndpoint.java

@@ -68,6 +68,11 @@
 import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
 /**
  * The external service endpoint acts as a location for external apis to query the current server of the external
  * supported API.
@@ -79,6 +84,7 @@
             ApiMediaType.VERSION_1_9_0, ApiMediaType.VERSION_1_10_0 })
 @RestService(name = "externalapiservice", title = "External API Service", notes = {},
              abstractText = "Provides a location for external apis to query the current server of the API.")
+@Tag(name = "External API", description = "The external service endpoint acts as a location for external apis to query the current server of the external supported API.")
 @Component(
     immediate = true,
     service = BaseEndpoint.class,
@@ -124,6 +130,11 @@ void activate(ComponentContext cc) {
   @Path("")
   @RestQuery(name = "getendpointinfo", description = "Returns key characteristics of the API such as the server name and the default version.", returnDescription = "", responses = {
           @RestResponse(description = "The api information is returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(
+      summary = "Get API information",
+      description = "Returns key characteristics of the API such as the server name and the default version."
+  )
+  @ApiResponse(responseCode = "200", description = "The api information is returned.")
   public Response getEndpointInfo() {
     Organization organization = securityService.getOrganization();
     String orgExternalAPIUrl = organization.getProperties().get(OpencastConstants.EXTERNAL_API_URL_ORG_PROPERTY);
@@ -143,6 +154,8 @@ public Response getEndpointInfo() {
   @Path("info/me")
   @RestQuery(name = "getuserinfo", description = "Returns information on the logged in user.", returnDescription = "", responses = {
           @RestResponse(description = "The user information is returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get user information", description = "Returns information on the logged in user.")
+  @ApiResponse(responseCode = "200", description = "The user information is returned.")
   public Response getUserInfo() {
     final User user = securityService.getUser();
 
@@ -156,6 +169,8 @@ public Response getUserInfo() {
   @Path("info/me/roles")
   @RestQuery(name = "getuserroles", description = "Returns current user's roles.", returnDescription = "", responses = {
           @RestResponse(description = "The set of roles is returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get user roles", description = "Returns current user's roles.")
+  @ApiResponse(responseCode = "200", description = "The set of roles is returned.")
   public Response getUserRoles() {
     final User user = securityService.getUser();
 
@@ -171,6 +186,8 @@ public Response getUserRoles() {
   @Path("info/organization")
   @RestQuery(name = "getorganizationinfo", description = "Returns the current organization.", returnDescription = "", responses = {
           @RestResponse(description = "The organization details are returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get organization information", description = "Returns the current organization.")
+  @ApiResponse(responseCode = "200", description = "The organization details are returned.")
   public Response getOrganizationInfo() {
     final Organization org = securityService.getOrganization();
 
@@ -184,6 +201,8 @@ public Response getOrganizationInfo() {
   @Path("info/organization/properties")
   @RestQuery(name = "getorganizationproperties", description = "Returns the current organization's properties.", returnDescription = "", responses = {
           @RestResponse(description = "The organization properties are returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get organization properties", description = "Returns the current organization's properties.")
+  @ApiResponse(responseCode = "200", description = "The organization properties are returned.")
   public Response getOrganizationProperties() {
     final Organization org = securityService.getOrganization();
 
@@ -199,6 +218,8 @@ public Response getOrganizationProperties() {
   @Path("info/organization/properties/engageuiurl")
   @RestQuery(name = "getorganizationpropertiesengageuiurl", description = "Returns the engage ui url property.", returnDescription = "", responses = {
           @RestResponse(description = "The engage ui url is returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get organization properties engage ui url", description = "Returns the engage ui url property.")
+  @ApiResponse(responseCode = "200", description = "The engage ui url is returned.")
   public Response getOrganizationPropertiesEngageUiUrl() {
     final Organization org = securityService.getOrganization();
 
@@ -220,6 +241,8 @@ public Response getOrganizationPropertiesEngageUiUrl() {
   @Path("version")
   @RestQuery(name = "getversion", description = "Returns a list of available version as well as the default version.", returnDescription = "", responses = {
           @RestResponse(description = "The default version is returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get available versions", description = "Returns a list of available version as well as the default version.")
+  @ApiResponse(responseCode = "200", description = "The default version is returned.")
   public Response getVersion() throws Exception {
     List<JValue> versions = new ArrayList<>();
     versions.add(v(ApiVersion.VERSION_1_0_0.toString()));
@@ -241,6 +264,9 @@ public Response getVersion() throws Exception {
   @Path("version/default")
   @RestQuery(name = "getversiondefault", description = "Returns the default version.", returnDescription = "", responses = {
           @RestResponse(description = "The default version is returned.", responseCode = HttpServletResponse.SC_OK) })
+  @Operation(summary = "Get default version", description = "Returns the default version.")
+  @ApiResponse(responseCode = "200", description = "The default version is returned.")
+  @Schema(name = "Version")
   public Response getVersionDefault() throws Exception {
     JValue json = obj(f("default", v(ApiVersion.CURRENT_VERSION.toString())));
     return RestUtil.R.ok(MediaType.APPLICATION_JSON_TYPE, serializer.toJson(json));

modules/external-api/src/main/java/org/opencastproject/external/endpoint/CaptureAgentsEndpoint.java

@@ -27,7 +27,7 @@
 import org.opencastproject.capture.admin.api.Agent;
 import org.opencastproject.capture.admin.api.CaptureAgentStateService;
 import org.opencastproject.external.common.ApiMediaType;
-import org.opencastproject.external.common.ApiResponses;
+import org.opencastproject.external.common.ApiResponseBuilder;
 import org.opencastproject.util.doc.rest.RestParameter;
 import org.opencastproject.util.doc.rest.RestParameter.Type;
 import org.opencastproject.util.doc.rest.RestQuery;
@@ -124,10 +124,10 @@ public Response getAgent(
     final Agent agent = agentStateService.getAgent(id);
 
     if (agent == null) {
-      return ApiResponses.notFound("Cannot find an agent with id '%s'.", id);
+      return ApiResponseBuilder.notFound("Cannot find an agent with id '%s'.", id);
     }
 
-    return ApiResponses.Json.ok(acceptHeader, generateJsonAgent(agent));
+    return ApiResponseBuilder.Json.ok(acceptHeader, generateJsonAgent(agent));
   }
 
   @GET
@@ -165,7 +165,7 @@ public Response getAgents(
         .map(a -> generateJsonAgent(a))
         .collect(Collectors.toList());
 
-    return ApiResponses.Json.ok(acceptHeader, arr(agentsJSON));
+    return ApiResponseBuilder.Json.ok(acceptHeader, arr(agentsJSON));
   }