Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added swagger based documentation #62

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Added swagger based documentation #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions job-service/server/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.4.0</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
Expand Down
46 changes: 41 additions & 5 deletions ...e/server/src/main/java/org/verapdf/webapp/jobservice/server/controller/JobController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,21 @@
package org.verapdf.webapp.jobservice.server.controller;

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.responses.ApiResponses;
import org.springframework.http.MediaType;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.verapdf.webapp.error.ErrorDTO;
import org.verapdf.webapp.error.exception.ConflictException;
import org.verapdf.webapp.error.exception.NotFoundException;
import org.verapdf.webapp.error.exception.VeraPDFBackendException;
import org.verapdf.webapp.jobservice.model.dto.JobDTO;
import org.verapdf.webapp.jobservice.model.dto.JobTaskDTO;
import org.verapdf.webapp.jobservice.model.entity.enums.Profile;
import org.verapdf.webapp.jobservice.model.entity.enums.TaskStatus;
import org.verapdf.webapp.jobservice.server.service.JobService;

import javax.validation.Valid;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

@RestController
Expand All @@ -26,23 +28,57 @@ public JobController(JobService jobService) {
this.jobService = jobService;
}

@Operation(summary = "Create job")
@ApiResponses(value = {
//TODO: const for response codes
@ApiResponse(responseCode = "200", description = "Successfully created job",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = JobDTO.class))})
})
@PostMapping
public JobDTO createJob(@RequestBody @Valid JobDTO jobDTO) {
return jobService.createJob(jobDTO);
}

@Operation(summary = "Get job data")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Found job",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = JobDTO.class))}),
@ApiResponse(responseCode = "404", description = "Job was not found", content = @Content)
})
@GetMapping("/{jobId}")
public JobDTO getJob(@PathVariable UUID jobId) throws NotFoundException {
return jobService.getJobById(jobId);
}

@Operation(summary = "Update job")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully updated job",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = JobDTO.class))}),
@ApiResponse(responseCode = "404", description = "Job was not found", content = @Content),
@ApiResponse(responseCode = "409", description = "Conflict while updating already started job",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = ErrorDTO.class))})
})
@PutMapping("/{jobId}")
public JobDTO updateJob(@PathVariable UUID jobId, @RequestBody @Valid JobDTO jobDTO) throws NotFoundException,
ConflictException {
return jobService.updateJob(jobId, jobDTO);
}

@Operation(summary = "Start job")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully started job execution",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = JobDTO.class))}),
@ApiResponse(responseCode = "500", description = "Exception while starting job",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = ErrorDTO.class))})
})
@PostMapping("/{jobId}/execution")
//TODO: why we dont throw not found exception on execution request?
public JobDTO startJobExecution(@PathVariable UUID jobId) throws VeraPDFBackendException {
return jobService.startJobExecution(jobId);
}
Expand Down
12 changes: 12 additions & 0 deletions ...rver/src/main/java/org/verapdf/webapp/jobservice/server/controller/ProfileController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
package org.verapdf.webapp.jobservice.server.controller;

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.responses.ApiResponses;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
Expand Down Expand Up @@ -33,6 +39,12 @@ public ProfileController() {
this.profiles.add(new ProfileDTO(Profile.PDFA_AUTO, false));
}

@Operation(summary = "Get list of all validation profiles")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully retrieved list of profiles",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = ProfileDTO.class))})
})
@GetMapping
public List<ProfileDTO> getProfiles() {
return profiles;
Expand Down
7 changes: 7 additions & 0 deletions job-service/server/src/main/resources/application.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,10 @@ verapdf:
listening-queue:
name: ${AMQP_SERVER_LISTENING_QUEUE_NAME}
max-size: ${AMQP_SERVER_LISTENING_QUEUE_MAX_SIZE}

springdoc:
api-docs:
path: /jobs/docs
swagger-ui:
path: /jobs/swagger.html
operations-sorter: method
5 changes: 5 additions & 0 deletions local-storage-service/server/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,11 @@
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.4.0</version>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
Expand Down
22 changes: 22 additions & 0 deletions ...rc/main/java/org/verapdf/webapp/localstorageservice/server/controller/FileController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
package org.verapdf.webapp.localstorageservice.server.controller;

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.responses.ApiResponses;
import org.springframework.core.annotation.Order;
import org.springframework.core.io.Resource;
import org.springframework.data.util.Pair;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import org.verapdf.webapp.error.ErrorDTO;
import org.verapdf.webapp.localstorageservice.model.dto.StoredFileDTO;
import org.verapdf.webapp.error.exception.NotFoundException;
import org.verapdf.webapp.error.exception.VeraPDFBackendException;
Expand All @@ -25,12 +31,28 @@ public FileController(StoredFileService storedFileService) {
this.storedFileService = storedFileService;
}

@Operation(summary = "Upload file")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Successfully uploaded file",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = StoredFileDTO.class))}),
@ApiResponse(responseCode = "500", description = "Error saving file on disk",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = ErrorDTO.class))})
})
@PostMapping
public StoredFileDTO uploadFile(@RequestPart("file") MultipartFile file,
@RequestPart("contentMD5") String contentMD5) throws VeraPDFBackendException {
return storedFileService.saveStoredFile(file, contentMD5);
}

//TODO: Swagger don't support same url and HTTP-method methods
@Operation(summary = "Download file with the specified id or get its data")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Found the file for being downloaded or to get its data"),
@ApiResponse(responseCode = "400", description = "Invalid id supplied", content = @Content),
@ApiResponse(responseCode = "404", description = "File was not found in db or on disk", content = @Content)
})
@GetMapping(value = "/{fileId}")
@Order(1)
public ResponseEntity<Resource> downloadFile(@PathVariable UUID fileId) throws NotFoundException,
Expand Down
7 changes: 7 additions & 0 deletions local-storage-service/server/src/main/resources/application.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,10 @@ verapdf:
files:
min-space-threshold: ${localstorage.disk.min.space.threshold:5GB}
base-dir: /opt/verapdf/localstorageservice/files

springdoc:
api-docs:
path: /files/docs
swagger-ui:
path: /files/swagger.html
operations-sorter: method