Skip to content

Commit

Permalink
docs(rest): generate OpenAPI docs for Project
Browse files Browse the repository at this point in the history 
Use `org.springdoc.springdoc-openapi-ui` to generate openAPI docs as
well as swagger UI.

Signed-off-by: Gaurav Mishra <[email protected]>
  • Loading branch information
@GMishx @heliocastro
GMishx authored and heliocastro committed Aug 11, 2023
1 parent 3bf53a1 commit ac8e9d1
Show file tree
Hide file tree
Showing 11 changed files with 663 additions and 90 deletions.
7 changes: 6 additions & 1 deletion pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -927,4 +932,4 @@
</profile>
</profiles>

</project>
</project>
45 changes: 44 additions & 1 deletion rest/resource-server/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>

Expand All @@ -331,4 +374,4 @@
</pluginRepositories>


</project>
</project>
59 changes: 56 additions & 3 deletions ...ource-server/src/main/java/org/eclipse/sw360/rest/resourceserver/Sw360ResourceServer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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 {
Expand All @@ -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";

Expand All @@ -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);
Expand All @@ -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
Expand Down Expand Up @@ -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));
}
}
48 changes: 48 additions & 0 deletions ...erver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/JacksonCustomizations.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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)
Expand Down
38 changes: 38 additions & 0 deletions ...ver/src/main/java/org/eclipse/sw360/rest/resourceserver/core/OpenAPIPaginationHelper.java
View file
Original file line number Diff line number Diff line change
@@ -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;
}
2 changes: 0 additions & 2 deletions .../org/eclipse/sw360/rest/resourceserver/moderationrequest/ModerationRequestController.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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> {
Expand Down
Loading

0 comments on commit ac8e9d1

Please sign in to comment.