SHIBUI-2274

Updated SWAGGER documentation to using springdoc-openapi-ui (v3). When ShibUI is running, swagger api documentation is now generated for all(most) of the public apis of the controllers. This documentation is available from the actuator url on port 9090 (default set in the properties file).

By default: http://localhost:9090/actuator/swagger-ui

README.md

@@ -2,14 +2,14 @@
 
 ## Requirements_
 
-* Java 8 (note that ONLY Java 8 is supported at this time; other later versions might work)
+* Java 11 (note that ONLY Java 11 is supported at this time; other later versions might work)
 
 ## Running
 
 There are currently 2 ways to run the application:
 
-1. As an executable
-1. deployed in a Java Servlet 3.0 container
+1. As an executable WAR using Java
+1. deployed in a Java Servlet 3.0 container such as Tomcat or Jetty
 
 Note that some features require encoded slashes in the URL. In tomcat (which is embedded in the war), this can be
 allowed with:
@@ -57,6 +57,7 @@ beginning with `#` are commented out.
 # Server Configuration
 #server.port=8080
 
+
 # Logging Configuration
 #logging.config=classpath:log4j2.xml
 #logging.level.org.springframework.web=ERROR
@@ -110,4 +111,10 @@ spring.profiles.active=default
 
 # Password for the default user. If not set, a password will be generated at startup
 #shibui.default-password=
-```
+
+springdoc.use-management-port=true
+springdoc.pathsToMatch=/entities, /api/**
+# This property enables the openapi and swagger-ui endpoints to be exposed beneath the actuator base path.
+management.endpoints.web.exposure.include=openapi, swagger-ui
+management.server.port=9090
+```

backend/build.gradle

@@ -171,9 +171,8 @@ dependencies {
     runtimeOnly 'org.mariadb.jdbc:mariadb-java-client:2.2.0'
     runtimeOnly 'mysql:mysql-connector-java:5.1.48'
 
-    //Swagger
-    compile 'io.springfox:springfox-swagger2:2.9.2'
-    compile 'io.springfox:springfox-swagger-ui:2.9.2'
+    //Swagger 3
+    implementation 'org.springdoc:springdoc-openapi-ui:1.6.8'
 
     testCompile "org.springframework.boot:spring-boot-starter-test"
     testCompile "org.springframework.security:spring-security-test"

backend/src/main/groovy/edu/internet2/tier/shibboleth/admin/ui/controller/EntityAttributesFiltersUiDefinitionController.groovy

@@ -4,6 +4,8 @@ import com.fasterxml.jackson.databind.ObjectMapper
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocation
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocationRegistry
 import edu.internet2.tier.shibboleth.admin.ui.service.JsonSchemaBuilderService
+import io.swagger.v3.oas.annotations.tags.Tag
+import io.swagger.v3.oas.annotations.tags.Tags
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.ResponseEntity
 import org.springframework.web.bind.annotation.GetMapping
@@ -24,6 +26,7 @@ import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR
  */
 @RestController
 @RequestMapping('/api/ui/EntityAttributesFilters')
+@Tags(value = [@Tag(name = "ui")])
 class EntityAttributesFiltersUiDefinitionController {
 
     @Autowired
@@ -58,4 +61,4 @@ class EntityAttributesFiltersUiDefinitionController {
     void init() {
         this.jsonSchemaLocation = entityAttributesFiltersSchema(this.jsonSchemaResourceLocationRegistry);
     }
-}
+}

backend/src/main/groovy/edu/internet2/tier/shibboleth/admin/ui/controller/MetadataResolverUiDefinitionController.groovy

@@ -3,18 +3,20 @@ package edu.internet2.tier.shibboleth.admin.ui.controller
 import com.fasterxml.jackson.databind.ObjectMapper
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocation
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocationRegistry
+import io.swagger.v3.oas.annotations.tags.Tag
+import io.swagger.v3.oas.annotations.tags.Tags
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.ResponseEntity
 import org.springframework.web.bind.annotation.GetMapping
 import org.springframework.web.bind.annotation.PathVariable
 import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RestController
 
+import static edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaLocationLookup.dynamicHttpMetadataProviderSchema
 import static edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaLocationLookup.filesystemMetadataProviderSchema
 import static edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaLocationLookup.localDynamicMetadataProviderSchema
-import static edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaLocationLookup.dynamicHttpMetadataProviderSchema
-import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR
 import static edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocation.SchemaType
+import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR
 
 /**
  * Controller implementing REST resource responsible for exposing structure definition for metadata resolvers user
@@ -25,6 +27,7 @@ import static edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResour
  */
 @RestController
 @RequestMapping('/api/ui/MetadataResolver')
+@Tags(value = [@Tag(name = "ui")])
 class MetadataResolverUiDefinitionController {
 
     @Autowired
@@ -66,4 +69,4 @@ class MetadataResolverUiDefinitionController {
     ResponseEntity<?> getResolverTypes() {
         return ResponseEntity.ok(SchemaType.getResolverTypes())
     }
-}
+}

backend/src/main/groovy/edu/internet2/tier/shibboleth/admin/ui/controller/MetadataSourcesUiDefinitionController.groovy

@@ -4,6 +4,8 @@ import com.fasterxml.jackson.databind.ObjectMapper
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocation
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocationRegistry
 import edu.internet2.tier.shibboleth.admin.ui.service.JsonSchemaBuilderService
+import io.swagger.v3.oas.annotations.tags.Tag
+import io.swagger.v3.oas.annotations.tags.Tags
 import org.slf4j.Logger
 import org.slf4j.LoggerFactory
 import org.springframework.beans.factory.annotation.Autowired
@@ -26,6 +28,7 @@ import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR
  */
 @RestController
 @RequestMapping('/api/ui/MetadataSources')
+@Tags(value = [@Tag(name = "ui")])
 class MetadataSourcesUiDefinitionController {
 
     private static final Logger logger = LoggerFactory.getLogger(MetadataSourcesUiDefinitionController.class);
@@ -63,4 +66,4 @@ class MetadataSourcesUiDefinitionController {
     void init() {
         this.jsonSchemaLocation = metadataSourcesSchema(this.jsonSchemaResourceLocationRegistry);
     }
-}
+}

backend/src/main/groovy/edu/internet2/tier/shibboleth/admin/ui/controller/NameIdFormatFilterUiDefinitionController.groovy

@@ -5,6 +5,8 @@ import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocat
 import edu.internet2.tier.shibboleth.admin.ui.jsonschema.JsonSchemaResourceLocationRegistry
 import edu.internet2.tier.shibboleth.admin.ui.service.JsonSchemaBuilderService
 import groovy.util.logging.Slf4j
+import io.swagger.v3.oas.annotations.tags.Tag
+import io.swagger.v3.oas.annotations.tags.Tags
 import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.http.ResponseEntity
 import org.springframework.web.bind.annotation.GetMapping
@@ -25,6 +27,7 @@ import static org.springframework.http.HttpStatus.INTERNAL_SERVER_ERROR
 @RestController
 @RequestMapping('/api/ui/NameIdFormatFilter')
 @Slf4j
+@Tags(value = [@Tag(name = "ui")])
 class NameIdFormatFilterUiDefinitionController {
 
     @Autowired
@@ -57,4 +60,4 @@ class NameIdFormatFilterUiDefinitionController {
     void init() {
         this.jsonSchemaLocation = nameIdFormatFilterSchema(this.jsonSchemaResourceLocationRegistry)
     }
-}
+}

backend/src/main/java/edu/internet2/tier/shibboleth/admin/ui/ShibbolethUiApplication.java

@@ -2,6 +2,8 @@
 
 import edu.internet2.tier.shibboleth.admin.ui.repository.MetadataResolverRepository;
 import edu.internet2.tier.shibboleth.admin.ui.service.MetadataResolverService;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Info;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -31,6 +33,7 @@
 @EnableScheduling
 @EnableWebSecurity
 @EnableAsync
+@OpenAPIDefinition(info=@Info(description = "The Shibboleth UI is specifically designed to help manage and edit metadata-driven configuration support for Shibboleth", title = "Shibboleth UI API", version = "1.0"))
 public class ShibbolethUiApplication extends SpringBootServletInitializer {
 
     private static final Logger logger = LoggerFactory.getLogger(ShibbolethUiApplication.class);
@@ -86,4 +89,4 @@ public void initializeResolvers(ApplicationStartedEvent e) {
                     });
         }
     }
-}
+}

backend/src/main/java/edu/internet2/tier/shibboleth/admin/ui/configuration/auto/WebSecurityConfig.java

@@ -135,6 +135,7 @@ protected void configure(AuthenticationManagerBuilder auth) throws Exception {
             public void configure(WebSecurity web) throws Exception {
                 super.configure(web);
                 web.httpFirewall(allowUrlEncodedSlashHttpFirewall());
+                web.ignoring().antMatchers("/actuator/**");
             }
         };
     }

backend/src/main/java/edu/internet2/tier/shibboleth/admin/ui/controller/ActivateController.java

@@ -2,6 +2,8 @@
 
 import javax.script.ScriptException;
 
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.tags.Tags;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -25,6 +27,7 @@
 
 @RestController
 @RequestMapping("/api/activate")
+@Tags(value = {@Tag(name = "activate")})
 public class ActivateController {
 
     @Autowired
@@ -62,4 +65,4 @@ public ResponseEntity<?> enableProvider(@PathVariable String resourceId, @PathVa
 
         return ResponseEntity.ok(existingResolver);
     }
-}
+}

backend/src/main/java/edu/internet2/tier/shibboleth/admin/ui/controller/AttributeBundleController.java

@@ -7,6 +7,8 @@
 import edu.internet2.tier.shibboleth.admin.ui.security.exception.GroupExistsConflictException;
 import edu.internet2.tier.shibboleth.admin.ui.security.model.Group;
 import edu.internet2.tier.shibboleth.admin.ui.service.AttributeBundleService;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.tags.Tags;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
@@ -25,6 +27,7 @@
 @RestController
 @RequestMapping("/api/custom/entity/bundles")
 @Slf4j
+@Tags(value = {@Tag(name = "bundles")})
 public class AttributeBundleController {
     @Autowired AttributeBundleService attributeBundleService;
 

backend/src/main/java/edu/internet2/tier/shibboleth/admin/ui/controller/ConfigurationController.java

@@ -3,19 +3,20 @@
 import edu.internet2.tier.shibboleth.admin.ui.configuration.CustomPropertiesConfiguration;
 import edu.internet2.tier.shibboleth.admin.ui.security.model.Role;
 import edu.internet2.tier.shibboleth.admin.ui.security.repository.RoleRepository;
-import edu.internet2.tier.shibboleth.admin.ui.service.EmailService;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.tags.Tags;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.ResponseEntity;
-import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
 
 import java.util.stream.Collectors;
 
 /**
  * @author Bill Smith (wsmith@unicon.net)
  */
-@Controller
+@RestController
 @RequestMapping(value = "/api")
 public class ConfigurationController {
 
@@ -26,12 +27,14 @@ public class ConfigurationController {
     RoleRepository roleRepository;
 
     @GetMapping(value = "/customAttributes")
+    @Tags(value = {@Tag(name = "attributes")})
     public ResponseEntity<?> getCustomAttributes() {
         return ResponseEntity.ok(customPropertiesConfiguration.getAttributes());
     }
 
     @GetMapping(value = "/supportedRoles")
+    @Tags(value = {@Tag(name = "admin")})
     public ResponseEntity<?> getSupportedRoles() {
         return ResponseEntity.ok(roleRepository.findAll().stream().map(Role::getName).collect(Collectors.toList()));
     }
-}
+}

backend/src/main/java/edu/internet2/tier/shibboleth/admin/ui/controller/CustomEntityAttributesDefinitionsController.java

@@ -1,10 +1,13 @@
 package edu.internet2.tier.shibboleth.admin.ui.controller;
 
+import edu.internet2.tier.shibboleth.admin.ui.domain.CustomEntityAttributeDefinition;
+import edu.internet2.tier.shibboleth.admin.ui.service.CustomEntityAttributesDefinitionService;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import io.swagger.v3.oas.annotations.tags.Tags;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
-import org.springframework.stereotype.Controller;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.web.bind.annotation.DeleteMapping;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -13,13 +16,12 @@
 import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
 
-import edu.internet2.tier.shibboleth.admin.ui.domain.CustomEntityAttributeDefinition;
-import edu.internet2.tier.shibboleth.admin.ui.service.CustomEntityAttributesDefinitionService;
-
-@Controller
+@RestController
 @RequestMapping(value = "/api/custom/entity")
+@Tags(value = {@Tag(name = "attributes")})
 public class CustomEntityAttributesDefinitionsController {
     @Autowired
     private CustomEntityAttributesDefinitionService caService;
@@ -102,4 +104,4 @@ public ResponseEntity<?> delete(@PathVariable String resourceId) {
         caService.deleteDefinition(cad);
         return ResponseEntity.noContent().build();
     }
-}
+}