docs(rest): generate OpenAPI docs for ProjectController

pom.xml

@@ -51,6 +51,7 @@
   <properties>
     <revision>17.0.${patchlevel}</revision>
     <patchlevel>0-SNAPSHOT</patchlevel>
+    <rest.version>1.0.0</rest.version>
 
     <!-- Build version properties -->
     <java_source.version>11</java_source.version>
@@ -150,6 +151,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 +932,4 @@
     </profile>
   </profiles>
 
-</project>
+</project>

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>
@@ -316,6 +336,29 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>com.internetitem</groupId>
+                <artifactId>write-properties-file-maven-plugin</artifactId>
+                <version>1.0.1</version>
+                <executions>
+                    <execution>
+                        <id>one</id>
+                        <phase>compile</phase>
+                        <goals>
+                            <goal>write-properties-file</goal>
+                        </goals>
+                        <configuration>
+                            <filename>restInfo.properties</filename>
+                            <properties>
+                                <property>
+                                    <name>sw360RestVersion</name>
+                                    <value>${rest.version}</value>
+                                </property>
+                            </properties>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 
@@ -331,4 +374,4 @@
     </pluginRepositories>
 
 
-</project>
+</project>

rest/resource-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,8 @@
 import org.springframework.web.filter.ForwardedHeaderFilter;
 import org.springframework.web.servlet.config.annotation.CorsRegistry;
 
+import java.util.*;
+
 @SpringBootApplication
 @Import(Sw360CORSFilter.class)
 public class Sw360ResourceServer extends SpringBootServletInitializer {
@@ -44,6 +53,8 @@ public class Sw360ResourceServer extends SpringBootServletInitializer {
     private int defaultPageSize;
 
     private static final String SW360_PROPERTIES_FILE_PATH = "/sw360.properties";
+    private static final String VERSION_INFO_PROPERTIES_FILE = "/restInfo.properties";
+    private static final String VERSION_INFO_KEY = "sw360RestVersion";
     private static final String CURIE_NAMESPACE = "sw360";
     private static final String APPLICATION_ID = "rest";
 
@@ -60,6 +71,9 @@ 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";
+    private static final Map<Object, Object> versionInfo;
 
     static {
         Properties props = CommonUtils.loadProperties(Sw360ResourceServer.class, SW360_PROPERTIES_FILE_PATH);
@@ -76,6 +90,17 @@ 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");
+
+        versionInfo = new HashMap<>();
+        Properties properties = CommonUtils.loadProperties(Sw360ResourceServer.class, VERSION_INFO_PROPERTIES_FILE, false);
+        versionInfo.putAll(properties);
+
+        SpringDocUtils.getConfig()
+                .replaceWithClass(org.springframework.data.domain.Pageable.class,
+                        OpenAPIPaginationHelper.class)
+                .replaceWithClass(org.springframework.data.domain.PageRequest.class,
+                        OpenAPIPaginationHelper.class);
     }
 
     @Bean
@@ -119,4 +144,32 @@ 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.");
+        Object restVersion = versionInfo.get(VERSION_INFO_KEY);
+        String restVersionString = "1.0.0";
+        if (restVersion != null) {
+            restVersionString = restVersion.toString();
+        }
+        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"))
+                        .version(restVersionString))
+                .servers(List.of(server));
+    }
 }

rest/resource-server/src/main/java/org/eclipse/sw360/rest/resourceserver/core/JacksonCustomizations.java

@@ -50,6 +50,7 @@
 import org.eclipse.sw360.rest.resourceserver.moderationrequest.ModerationPatch;
 import org.eclipse.sw360.rest.resourceserver.project.EmbeddedProject;
 import org.eclipse.sw360.rest.resourceserver.project.EmbeddedProjectDTO;
+import org.springdoc.core.SpringDocUtils;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
@@ -112,6 +113,53 @@ public Sw360Module() {
             setMixInAnnotation(ProjectDTO.class, Sw360Module.ProjectDTOMixin.class);
             setMixInAnnotation(EmbeddedProjectDTO.class, Sw360Module.EmbeddedProjectDTOMixin.class);
             setMixInAnnotation(ReleaseNode.class, Sw360Module.ReleaseNodeMixin.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(ComponentDTO.class, Sw360Module.ComponentDTOMixin.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)
+                    .replaceWithClass(ProjectDTO.class, Sw360Module.ProjectDTOMixin.class)
+                    .replaceWithClass(EmbeddedProjectDTO.class, Sw360Module.EmbeddedProjectDTOMixin.class)
+                    .replaceWithClass(ReleaseNode.class, Sw360Module.ReleaseNodeMixin.class);
         }
 
         @JsonInclude(JsonInclude.Include.NON_NULL)

rest/resource-server/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;
+}

rest/resource-server/src/main/java/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> {