doc(rest): Generate OpenAPI docs for Project

Use `org.springdoc.springdoc-openapi-ui` to generate openAPI docs as well as swagger UI. Signed-off-by: Gaurav Mishra <gmishx@gmail.com>
eclipse-sw360 · Jul 28, 2023 · d8740cf · d8740cf
1 parent c5185ab
commit d8740cf
Show file tree

Hide file tree

Showing 10 changed files with 565 additions and 79 deletions.
diff --git a/pom.xml b/pom.xml
@@ -150,6 +150,10 @@
     <spring-restdocs.version>2.0.6.RELEASE</spring-restdocs.version>
     <spring-security-jwt.version>1.1.1.RELEASE</spring-security-jwt.version>
     <spring-security-oauth2.version>2.5.1.RELEASE</spring-security-oauth2.version>
+    <springdoc-openapi-hateos.version>1.7.0</springdoc-openapi-hateos.version>
+    <springdoc-openapi-ui.version>1.7.0</springdoc-openapi-ui.version>
+    <springdoc-openapi-security.version>1.7.0</springdoc-openapi-security.version>
+    <springdoc-openapi-webmvc.version>1.7.0</springdoc-openapi-webmvc.version>
     <springframework.version>5.3.27</springframework.version>
     <thrift.version>0.16.0</thrift.version>
     <tika.version>1.28.5</tika.version>
@@ -927,4 +931,4 @@
     </profile>
   </profiles>
 
-</project>
+</project>
diff --git a/rest/resource-server/pom.xml b/rest/resource-server/pom.xml
@@ -206,6 +206,26 @@
             <artifactId>jose4j</artifactId>
             <version>0.9.3</version>
         </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-ui</artifactId>
+            <version>${springdoc-openapi-ui.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-hateoas</artifactId>
+            <version>${springdoc-openapi-hateos.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-security</artifactId>
+            <version>${springdoc-openapi-security.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-webmvc-core</artifactId>
+            <version>${springdoc-openapi-webmvc.version}</version>
+        </dependency>
     </dependencies>
     <dependencyManagement>
         <dependencies>
@@ -331,4 +351,4 @@
     </pluginRepositories>
 
 
-</project>
+</project>
diff --git a/...ource-server/src/main/java/org/eclipse/sw360/rest/resourceserver/Sw360ResourceServer.java b/...ource-server/src/main/java/org/eclipse/sw360/rest/resourceserver/Sw360ResourceServer.java
@@ -10,15 +10,22 @@
 
 package org.eclipse.sw360.rest.resourceserver;
 
-import java.util.Properties;
-import java.util.Set;
-
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.security.OAuthFlow;
+import io.swagger.v3.oas.models.security.OAuthFlows;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import io.swagger.v3.oas.models.servers.Server;
 import org.eclipse.sw360.datahandler.common.CommonUtils;
 import org.eclipse.sw360.datahandler.thrift.users.UserGroup;
 import org.eclipse.sw360.rest.common.PropertyUtils;
 import org.eclipse.sw360.rest.common.Sw360CORSFilter;
+import org.eclipse.sw360.rest.resourceserver.core.OpenAPIPaginationHelper;
 import org.eclipse.sw360.rest.resourceserver.core.RestControllerHelper;
 import org.eclipse.sw360.rest.resourceserver.security.apiToken.ApiTokenAuthenticationFilter;
+import org.springdoc.core.SpringDocUtils;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.builder.SpringApplicationBuilder;
@@ -34,6 +41,10 @@
 import org.springframework.web.filter.ForwardedHeaderFilter;
 import org.springframework.web.servlet.config.annotation.CorsRegistry;
 
+import java.util.List;
+import java.util.Properties;
+import java.util.Set;
+
 @SpringBootApplication
 @Import(Sw360CORSFilter.class)
 public class Sw360ResourceServer extends SpringBootServletInitializer {
@@ -60,6 +71,8 @@ public class Sw360ResourceServer extends SpringBootServletInitializer {
     public static final UserGroup CONFIG_ADMIN_ACCESS_USERGROUP;
     private static final String DEFAULT_WRITE_ACCESS_USERGROUP = UserGroup.SW360_ADMIN.name();
     private static final String DEFAULT_ADMIN_ACCESS_USERGROUP = UserGroup.SW360_ADMIN.name();
+    private static final String SERVER_PATH_URL;
+    private static final String APPLICATION_NAME = "/resource";
 
     static {
         Properties props = CommonUtils.loadProperties(Sw360ResourceServer.class, SW360_PROPERTIES_FILE_PATH);
@@ -76,6 +89,13 @@ public class Sw360ResourceServer extends SpringBootServletInitializer {
                 System.getProperty("RunRestForceUpdateTest", props.getProperty("rest.force.update.enabled", "false")));
         CONFIG_WRITE_ACCESS_USERGROUP = UserGroup.valueOf(props.getProperty("rest.write.access.usergroup", DEFAULT_WRITE_ACCESS_USERGROUP));
         CONFIG_ADMIN_ACCESS_USERGROUP = UserGroup.valueOf(props.getProperty("rest.admin.access.usergroup", DEFAULT_ADMIN_ACCESS_USERGROUP));
+        SERVER_PATH_URL = props.getProperty("backend.url", "http://localhost:8080");
+
+        SpringDocUtils.getConfig()
+                .replaceWithClass(org.springframework.data.domain.Pageable.class,
+                        OpenAPIPaginationHelper.class)
+                .replaceWithClass(org.springframework.data.domain.PageRequest.class,
+                        OpenAPIPaginationHelper.class);
     }
 
     @Bean
@@ -119,4 +139,26 @@ public FilterRegistrationBean<ForwardedHeaderFilter> forwardedHeaderFilter() {
         bean.setFilter(new ForwardedHeaderFilter());
         return bean;
     }
+
+    @Bean
+    public OpenAPI customOpenAPI() {
+        Server server = new Server();
+        server.setUrl(SERVER_PATH_URL + APPLICATION_NAME + REST_BASE_PATH);
+        server.setDescription("Current instance.");
+        return new OpenAPI()
+                .components(new Components()
+                        .addSecuritySchemes("tokenAuth",
+                                new SecurityScheme().type(SecurityScheme.Type.APIKEY).name("Authorization")
+                                        .in(SecurityScheme.In.HEADER)
+                                        .description("Enter the token with the `Token ` prefix, e.g. \"Token abcde12345\"."))
+                        .addSecuritySchemes("oauth",
+                                new SecurityScheme().type(SecurityScheme.Type.OAUTH2)
+                                        .flows(new OAuthFlows().password(new OAuthFlow()
+                                                .tokenUrl(SERVER_PATH_URL + "/authorization/oauth/token")
+                                                .refreshUrl(SERVER_PATH_URL + "/authorization/oauth/token"))
+                                        )))
+                .info(new Info().title("SW360 API").license(new License().name("EPL-2.0")
+                        .url("https://github.com/eclipse-sw360/sw360/blob/main/LICENSE")))
+                .servers(List.of(server));
+    }
 }
diff --git a/...erver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/JacksonCustomizations.java b/...erver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/JacksonCustomizations.java
@@ -48,6 +48,7 @@
 import org.eclipse.sw360.rest.resourceserver.moderationrequest.EmbeddedModerationRequest;
 import org.eclipse.sw360.rest.resourceserver.moderationrequest.ModerationPatch;
 import org.eclipse.sw360.rest.resourceserver.project.EmbeddedProject;
+import org.springdoc.core.SpringDocUtils;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
@@ -105,6 +106,49 @@ public Sw360Module() {
             setMixInAnnotation(EmbeddedModerationRequest.class, Sw360Module.EmbeddedModerationRequestMixin.class);
             setMixInAnnotation(ImportBomRequestPreparation.class, Sw360Module.ImportBomRequestPreparationMixin.class);
             setMixInAnnotation(ModerationPatch.class, Sw360Module.ModerationPatchMixin.class);
+
+            // Make spring doc aware of the mixin(s)
+            SpringDocUtils.getConfig()
+                    .replaceWithClass(Project.class, Sw360Module.ProjectMixin.class)
+                    .replaceWithClass(MultiStatus.class, MultiStatusMixin.class)
+                    .replaceWithClass(User.class, Sw360Module.UserMixin.class)
+                    .replaceWithClass(Component.class, Sw360Module.ComponentMixin.class)
+                    .replaceWithClass(Release.class, Sw360Module.ReleaseMixin.class)
+                    .replaceWithClass(ReleaseLink.class, Sw360Module.ReleaseLinkMixin.class)
+                    .replaceWithClass(ClearingReport.class, Sw360Module.ClearingReportMixin.class)
+                    .replaceWithClass(Attachment.class, Sw360Module.AttachmentMixin.class)
+                    .replaceWithClass(AttachmentDTO.class, Sw360Module.AttachmentDTOMixin.class)
+                    .replaceWithClass(UsageAttachment.class, Sw360Module.UsageAttachmentMixin.class)
+                    .replaceWithClass(ProjectUsage.class, Sw360Module.ProjectUsageMixin.class)
+                    .replaceWithClass(Vendor.class, Sw360Module.VendorMixin.class)
+                    .replaceWithClass(License.class, Sw360Module.LicenseMixin.class)
+                    .replaceWithClass(Obligation.class, Sw360Module.ObligationMixin.class)
+                    .replaceWithClass(Vulnerability.class, Sw360Module.VulnerabilityMixin.class)
+                    .replaceWithClass(VulnerabilityState.class, Sw360Module.VulnerabilityStateMixin.class)
+                    .replaceWithClass(ReleaseVulnerabilityRelationDTO.class, Sw360Module.ReleaseVulnerabilityRelationDTOMixin.class)
+                    .replaceWithClass(VulnerabilityDTO.class, Sw360Module.VulnerabilityDTOMixin.class)
+                    .replaceWithClass(VulnerabilityApiDTO.class, Sw360Module.VulnerabilityApiDTOMixin.class)
+                    .replaceWithClass(EccInformation.class, Sw360Module.EccInformationMixin.class)
+                    .replaceWithClass(EmbeddedProject.class, Sw360Module.EmbeddedProjectMixin.class)
+                    .replaceWithClass(ExternalToolProcess.class, Sw360Module.ExternalToolProcessMixin.class)
+                    .replaceWithClass(ExternalToolProcessStep.class, Sw360Module.ExternalToolProcessStepMixin.class)
+                    .replaceWithClass(COTSDetails.class, Sw360Module.COTSDetailsMixin.class)
+                    .replaceWithClass(ClearingInformation.class, Sw360Module.ClearingInformationMixin.class)
+                    .replaceWithClass(Repository.class, Sw360Module.RepositoryMixin.class)
+                    .replaceWithClass(SearchResult.class, Sw360Module.SearchResultMixin.class)
+                    .replaceWithClass(ChangeLogs.class, Sw360Module.ChangeLogsMixin.class)
+                    .replaceWithClass(ChangedFields.class, Sw360Module.ChangedFieldsMixin.class)
+                    .replaceWithClass(ReferenceDocData.class, Sw360Module.ReferenceDocDataMixin.class)
+                    .replaceWithClass(ClearingRequest.class, Sw360Module.ClearingRequestMixin.class)
+                    .replaceWithClass(Comment.class, Sw360Module.CommentMixin.class)
+                    .replaceWithClass(ProjectReleaseRelationship.class, Sw360Module.ProjectReleaseRelationshipMixin.class)
+                    .replaceWithClass(ReleaseVulnerabilityRelation.class, Sw360Module.ReleaseVulnerabilityRelationMixin.class)
+                    .replaceWithClass(VerificationStateInfo.class, Sw360Module.VerificationStateInfoMixin.class)
+                    .replaceWithClass(ProjectProjectRelationship.class, Sw360Module.ProjectProjectRelationshipMixin.class)
+                    .replaceWithClass(ModerationRequest.class, Sw360Module.ModerationRequestMixin.class)
+                    .replaceWithClass(EmbeddedModerationRequest.class, Sw360Module.EmbeddedModerationRequestMixin.class)
+                    .replaceWithClass(ImportBomRequestPreparation.class, Sw360Module.ImportBomRequestPreparationMixin.class)
+                    .replaceWithClass(ModerationPatch.class, Sw360Module.ModerationPatchMixin.class);
         }
 
         @JsonInclude(JsonInclude.Include.NON_NULL)

diff --git a/...ver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/OpenAPIPaginationHelper.java b/...ver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/OpenAPIPaginationHelper.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright Siemens AG, 2023. Part of the SW360 Portal Project.
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+package org.eclipse.sw360.rest.resourceserver.core;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * Pojo class to show correct options for pagination in OpenAPI doc.
+ */
+//@JsonMixin
+@AllArgsConstructor
+@NoArgsConstructor
+@Data
+@Builder
+@Schema
+public class OpenAPIPaginationHelper {
+    @Schema(description = "Page number to fetch, starts from 0", type = "int",
+            defaultValue = "0", name = "page")
+    private int pageNumber;
+    @Schema(description = "Number of entries per page", type = "int",
+            defaultValue = "10", name = "page_entries")
+    private int pageEntries;
+    @Schema(description = "Sorting of entries", type = "string",
+            example = "name,desc", name = "sort")
+    private String sort;
+}
diff --git a/.../org/eclipse/sw360/rest/resourceserver/moderationrequest/ModerationRequestController.java b/.../org/eclipse/sw360/rest/resourceserver/moderationrequest/ModerationRequestController.java
@@ -49,7 +49,6 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestMethod;
 import org.springframework.web.bind.annotation.RequestParam;
-import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.client.HttpClientErrorException;
 
 import javax.servlet.http.HttpServletRequest;
@@ -63,7 +62,6 @@
 import static org.eclipse.sw360.rest.resourceserver.moderationrequest.Sw360ModerationRequestService.isOpenModerationRequest;
 import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.linkTo;
 
-@RestController
 @BasePathAwareController
 @RequiredArgsConstructor(onConstructor = @__(@Autowired))
 public class ModerationRequestController implements RepresentationModelProcessor<RepositoryLinksResource> {