Merge pull request #567 from nscuro/openapi-v3

Remove Swagger integration
stevespringett · May 17, 2024 · e747ed5 · e747ed5
2 parents 2e0b946 + 85a6936
commit e747ed5
Show file tree

Hide file tree

Showing 9 changed files with 21 additions and 96 deletions.
diff --git a/README.md b/README.md
@@ -33,10 +33,6 @@ at its core. The servers resources are stateless and do not rely
 on sessions. JSON Web Tokens (JWT) are used to maintain some state
 and are signed with an HMAC.
 
-* **API Documentation** - 
-Swagger support is built-in, allowing you to document APIs and generate
-Swagger 2.0 definitions with ease.
-
 * **Authentications** - 
 Alpine supports multiple types of principals including LDAP users and 
 API keys, both of which can be integrated into teams for access control.
@@ -77,7 +73,6 @@ The following features are free and require little or no coding just for using A
 * Authentication via API keys
 * Authentication via JWT
 * Stateless API-first design
-* Automatic generation of Swagger 2.0 definitions
 * REST resources are locked down by default (requires authentication)
 * Configurable enforcement of authentication and authorization
 * Built-in support for BCrypt for the hashing and salting of passwords for managed users

diff --git a/alpine-server/pom.xml b/alpine-server/pom.xml
@@ -118,17 +118,9 @@
             <groupId>org.glassfish</groupId>
             <artifactId>javax.json</artifactId>
         </dependency>
-        <!-- todo: update swagger when available -->
-        <!-- https://github.com/swagger-api/swagger-core/issues/1594 -->
-        <dependency>
-            <groupId>io.swagger</groupId>
-            <artifactId>swagger-jersey2-jaxrs</artifactId>
-            <exclusions>
-                <exclusion>
-                    <groupId>javax.validation</groupId>
-                    <artifactId>validation-api</artifactId>
-                </exclusion>
-            </exclusions>
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations</artifactId>
         </dependency>
         <!-- Persistence -->
         <dependency>

diff --git a/alpine-server/src/main/java/alpine/server/AlpineServlet.java b/alpine-server/src/main/java/alpine/server/AlpineServlet.java
@@ -21,22 +21,13 @@
 import alpine.Config;
 import alpine.common.logging.Logger;
 import alpine.security.crypto.KeyManager;
-import io.jsonwebtoken.lang.Collections;
-import io.swagger.jaxrs.config.SwaggerContextService;
-import io.swagger.models.Info;
-import io.swagger.models.Swagger;
-import io.swagger.models.auth.ApiKeyAuthDefinition;
-import io.swagger.models.auth.In;
 import org.glassfish.jersey.servlet.ServletContainer;
 import org.owasp.security.logging.util.IntervalLoggerController;
 import org.owasp.security.logging.util.SecurityLoggingFactory;
 import org.owasp.security.logging.util.SecurityUtil;
 
 import javax.servlet.ServletConfig;
-import javax.servlet.ServletContext;
 import javax.servlet.ServletException;
-import javax.servlet.ServletRegistration;
-import java.util.Collection;
 
 /**
  * The AlpineServlet is the main servlet which extends
@@ -56,37 +47,14 @@ public class AlpineServlet extends ServletContainer {
     /**
      * Overrides the servlet init method and loads sets the InputStream necessary
      * to load application.properties.
+     *
      * @throws ServletException a general error that occurs during initialization
      */
     @Override
     public void init(ServletConfig config) throws ServletException {
         LOGGER.info("Starting " + Config.getInstance().getApplicationName());
         super.init(config);
 
-        final Info info = new Info()
-                .title(Config.getInstance().getApplicationName() + " API")
-                .version(Config.getInstance().getApplicationVersion());
-
-        final Swagger swagger = new Swagger()
-                .info(info)
-                .securityDefinition("X-Api-Key", new ApiKeyAuthDefinition("X-Api-Key", In.HEADER));
-
-        // Dynamically get the url-pattern from web.xml and use that as the 'baseUrl' for
-        // the API documentation
-        final ServletContext servletContext = getServletContext();
-        final ServletRegistration servletRegistration = servletContext.getServletRegistration(config.getServletName());
-        final Collection<String> mappings = servletRegistration.getMappings();
-        if (! Collections.isEmpty(mappings)) {
-            String baseUrl = mappings.iterator().next();
-            if (baseUrl.charAt(0) != '/') {
-                baseUrl = "/" + baseUrl;
-            }
-            baseUrl = baseUrl.replace("/*", "").replaceAll("\\/$", "");
-            swagger.basePath(config.getServletContext().getContextPath() + baseUrl);
-        }
-
-        new SwaggerContextService().withServletConfig(config).updateSwagger(swagger).initScanner();
-
         // Initializes the KeyManager
         KeyManager.getInstance();
 

diff --git a/alpine-server/src/main/java/alpine/server/filters/AuthenticationFilter.java b/alpine-server/src/main/java/alpine/server/filters/AuthenticationFilter.java
@@ -36,7 +36,7 @@
 
 /**
  * A filter that ensures that all calls going through this filter are
- * authenticated. Exceptions are made for swagger URLs.
+ * authenticated.
  *
  * @see AuthenticationFeature
  * @author Steve Springett
@@ -56,10 +56,6 @@ public void filter(ContainerRequestContext requestContext) {
             if (HttpMethod.OPTIONS.equals(request.getMethod())) {
                 return;
             }
-            // Bypass authentication for swagger
-            if (request.getRequestUri().getPath().contains("/api/swagger")) {
-                return;
-            }
 
             Principal principal = null;
 

diff --git a/alpine-server/src/main/java/alpine/server/resources/VersionResource.java b/alpine-server/src/main/java/alpine/server/resources/VersionResource.java
@@ -20,8 +20,11 @@
 
 import alpine.model.About;
 import alpine.server.auth.AuthenticationNotRequired;
-import io.swagger.annotations.Api;
-import io.swagger.annotations.ApiOperation;
+import io.swagger.v3.oas.annotations.Operation;
+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.tags.Tag;
 
 import javax.ws.rs.GET;
 import javax.ws.rs.Path;
@@ -38,16 +41,16 @@
  * @since 1.0.0
  */
 @Path("/version")
-@Produces(MediaType.APPLICATION_JSON)
-@Api(value = "version")
+@Tag(name = "version")
 public final class VersionResource {
 
     @GET
-    @ApiOperation(
-            value = "Returns application version information",
-            notes = "Returns a simple json object containing the name of the application and the version",
-            response = About.class
+    @Produces(MediaType.APPLICATION_JSON)
+    @Operation(
+            summary = "Returns application version information",
+            description = "Returns a simple json object containing the name of the application and the version"
     )
+    @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = About.class)))
     @AuthenticationNotRequired
     public Response getVersion() {
         return Response.ok(new GenericEntity<>(new About()) { }).build();

diff --git a/example/src/main/webapp/WEB-INF/web.xml b/example/src/main/webapp/WEB-INF/web.xml
@@ -22,7 +22,7 @@
         <servlet-class>alpine.AlpineServlet</servlet-class>
         <init-param>
             <param-name>jersey.config.server.provider.packages</param-name>
-            <param-value>io.swagger.jaxrs.listing,alpine.filters,alpine.resources,com.example.resources</param-value>
+            <param-value>alpine.filters,alpine.resources,com.example.resources</param-value>
         </init-param>
         <init-param>
             <param-name>jersey.config.server.provider.classnames</param-name>

diff --git a/example/src/main/webapp/index.html b/example/src/main/webapp/index.html
@@ -50,7 +50,6 @@ <h3>Application Features</h3>
                         <li>Authentication via API keys</li>
                         <li>Authentication via JWT</li>
                         <li>Stateless API-first design</li>
-                        <li>Automatic generation of Swagger 2.0 definitions</li>
                         <li>REST resources are locked down by default (requires authentication)</li>
                         <li>Configurable enforcement of authentication and authorization</li>
                         <li>Built-in support for BCrypt for the hashing and salting of passwords for managed users</li>
@@ -77,12 +76,6 @@ <h3>Build Features</h3>
                 <div class="tab-pane" id="three">
                     <h3>Demos</h3>
 
-                    <h5>Swagger Definition</h5>
-                    <p>Alpine applications have Swagger support built-in. Simply annotate your REST resources to extend the definition.</p>
-                    <button id="swagger-button" class="button-primary">Get Swagger</button>
-                    <label for="swagger-content">Response</label>
-                    <textarea id="swagger-content" readonly class="u-full-width" style="height:150px;"></textarea>
-
                     <hr/>
 
                     <h5>Version Resource</h5>

diff --git a/example/src/main/webapp/js/example.js b/example/src/main/webapp/js/example.js
@@ -1,14 +1,3 @@
-
-function getSwagger() {
-    $.ajax({
-        type: "GET",
-        url: "api/swagger.json",
-        success: function (data) {
-            $('#swagger-content').val(JSON.stringify(data, null, 4));
-        }
-    });
-}
-
 function getVersion() {
     $.ajax({
         type: "GET",
@@ -36,9 +25,6 @@ function assertCredentials() {
 }
 
 $(document).ready(function() {
-    $("#swagger-button").click(function(){
-        getSwagger();
-    });
     $("#version-button").click(function(){
         getVersion();
     });

diff --git a/pom.xml b/pom.xml
@@ -193,7 +193,7 @@
         <lib.owasp.encoder.version>1.2.3</lib.owasp.encoder.version>
         <lib.owasp.security-logging.version>1.1.7</lib.owasp.security-logging.version>
         <lib.slf4j.version>2.0.12</lib.slf4j.version>
-        <lib.swagger.jersey.version>1.6.11</lib.swagger.jersey.version>
+        <lib.swagger.version>2.2.22</lib.swagger.version>
         <!-- Unit test libraries -->
         <lib.junit.version>4.13.2</lib.junit.version>
         <lib.mockito.version>5.5.0</lib.mockito.version>
@@ -288,18 +288,10 @@
                 <artifactId>javax.json</artifactId>
                 <version>${lib.jsr353-impl.version}</version>
             </dependency>
-            <!-- todo: update swagger when available -->
-            <!-- https://github.com/swagger-api/swagger-core/issues/1594 -->
             <dependency>
-                <groupId>io.swagger</groupId>
-                <artifactId>swagger-jersey2-jaxrs</artifactId>
-                <version>${lib.swagger.jersey.version}</version>
-                <exclusions>
-                    <exclusion>
-                        <groupId>javax.validation</groupId>
-                        <artifactId>validation-api</artifactId>
-                    </exclusion>
-                </exclusions>
+                <groupId>io.swagger.core.v3</groupId>
+                <artifactId>swagger-annotations</artifactId>
+                <version>${lib.swagger.version}</version>
             </dependency>
             <!-- Persistence -->
             <dependency>