pom.xml

@@ -42,6 +42,16 @@
             <groupId>org.flywaydb</groupId>
             <artifactId>flyway-mysql</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.6.0</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.therapi</groupId>
+            <artifactId>therapi-runtime-javadoc</artifactId>
+            <version>0.15.0</version>
+        </dependency>
 
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -82,6 +92,23 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>com.github.therapi</groupId>
+                            <artifactId>therapi-runtime-javadoc-scribe</artifactId>
+                            <version>0.15.0</version>
+                        </path>
+                        <path>
+                            <groupId>org.springframework.boot</groupId>
+                            <artifactId>spring-boot-configuration-processor</artifactId>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 

src/main/java/se/su/dsv/whisperapi/WhisperApiApplication.java

@@ -1,5 +1,11 @@
 package se.su.dsv.whisperapi;
 
+import io.swagger.v3.core.converter.ModelConverters;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import org.springdoc.core.customizers.OpenApiCustomizer;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
@@ -13,9 +19,12 @@ import org.springframework.security.config.Customizer;
 import org.springframework.security.config.annotation.web.builders.HttpSecurity;
 import org.springframework.security.web.SecurityFilterChain;
 import org.springframework.web.filter.ForwardedHeaderFilter;
+import se.su.dsv.whisperapi.core.Callback;
 import se.su.dsv.whisperapi.core.TranscriptionRepository;
 import se.su.dsv.whisperapi.core.TranscriptionService;
 
+import java.util.Map;
+
 @SpringBootApplication
 @EnableConfigurationProperties(WhisperFrontendConfiguration.class)
 @EnableScheduling
@@ -79,4 +88,17 @@ public class WhisperApiApplication {
     public SendOutCallbacksJob sendOutCallbacksJob(TranscriptionService transcriptionService) {
         return new SendOutCallbacksJob(transcriptionService);
     }
+
+    @Bean
+    public OpenApiCustomizer customOpenAPI() {
+        return openApi -> {
+            ModelConverters modelConverters = ModelConverters.getInstance();
+            Map<String, Schema> extraSchemas = modelConverters.readAll(Callback.class);
+            extraSchemas.forEach(openApi.getComponents()::addSchemas);
+            openApi.getComponents().addSecuritySchemes("basicAuth", new SecurityScheme()
+                    .type(SecurityScheme.Type.HTTP)
+                    .in(SecurityScheme.In.HEADER)
+                    .scheme("basic"));
+        };
+    }
 }

src/main/java/se/su/dsv/whisperapi/api/ApiController.java

@@ -1,5 +1,9 @@
 package se.su.dsv.whisperapi.api;
 
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
+import io.swagger.v3.oas.annotations.Hidden;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
 import org.springframework.core.io.InputStreamResource;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
@@ -39,9 +43,21 @@ import java.util.UUID;
 
 /**
  * For submitting jobs programmatically via a JSON HTTP API.
- * Submitting jobs programmatically is only available to applications with
- * shared filesystem access.
+ * The entry point for the API is {@code POST /api/transcriptions}.
+ * <p>
+ * Transcribing files is a three-step process;
+ * <ol>
+ *     <li>Create a transcription using {@code POST /api/transcriptions}</li>
+ *     <li>Attach source files to be transcribed by by {@code POST}ing to the {@code attach-source-file} relation link</li>
+ *     <li>Submit the transcription for processing using {@code PUT} on the {@code submit-job} relation link</li>
+ * </ol>
+ * <p>
+ * Once processing is completed, successful or not, your callback will be called with a {@code Callback}
  */
+@OpenAPIDefinition(
+        security = @SecurityRequirement(name = "basicAuth"),
+        externalDocs = @ExternalDocumentation(description = "Wiki", url = "https://gitea.dsv.su.se/DMC/whisper-frontend/wiki")
+)
 @RestController
 @RequestMapping(consumes = "application/json", produces = "application/json")
 public class ApiController {
@@ -53,6 +69,14 @@ public class ApiController {
         this.transcriptionService = transcriptionService;
     }
 
+    /**
+     * Create a new transcription job. The job will be created in a pending state and will not start processing until
+     * the source files have been attached and the job has been submitted.
+     * @param createTranscriptionRequest parameters of the new transcription
+     * @return the transcription job id and links to attach source files
+     * @see #submitTranscriptionJob(Principal, UriComponentsBuilder, String) Submitting the job for processing
+     * @see #uploadFileToBeTranscribed(Principal, String, String, UriComponentsBuilder, InputStream) Attach a source file to be transcribed
+     */
     @PostMapping("/api/transcriptions")
     public TranscriptionResponse submitTranscriptionJob(
             Principal owner,
@@ -204,6 +228,9 @@ public class ApiController {
         };
     }
 
+    /**
+     * Submit the job for processing.
+     */
     @PostMapping(value = "/api/transcriptions/{id}/job", consumes = "*/*")
     public ResponseEntity<Void> submitTranscriptionJob(
             Principal owner,
@@ -229,6 +256,7 @@ public class ApiController {
         }
     }
 
+    @Hidden
     @PostMapping("/api/transcriptions/job/callback/{jobId}")
     public ResponseEntity<Void> jobCallback(
             @PathVariable("jobId") String jobId,