From 8954c6a70577b1277de8195abc0b077e89a76744 Mon Sep 17 00:00:00 2001 From: Kamil Sulejewski Date: Mon, 3 Mar 2025 22:18:46 +0100 Subject: [PATCH] doc: added swagger documentation for api. --- .../controller/CommitTranslateController.java | 17 +++++++ .../craft/flow/CommitFlowController.java | 20 +++++++- .../CommitCraftTemplateController.java | 46 +++++++++++------ .../CommitTemplateGenerateController.java | 50 ++++++++++++++++++- .../templates/dedicated-meta-schema.json | 15 +----- 5 files changed, 117 insertions(+), 31 deletions(-) diff --git a/src/main/java/pl/commit/craft/controller/CommitTranslateController.java b/src/main/java/pl/commit/craft/controller/CommitTranslateController.java index bf4e3ed..cb5edf2 100644 --- a/src/main/java/pl/commit/craft/controller/CommitTranslateController.java +++ b/src/main/java/pl/commit/craft/controller/CommitTranslateController.java @@ -1,11 +1,17 @@ package pl.commit.craft.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 io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.*; import pl.commit.craft.service.CommitTranslateService; @RestController @RequestMapping("/api/v1/commit-translate") +@Tag(name = "Commit Translation Controller", description = "Translate commit wit deepl api") public class CommitTranslateController { private final CommitTranslateService commitTranslateService; @@ -18,8 +24,19 @@ public CommitTranslateController(CommitTranslateService commitTranslateService) summary = "Generate commit translation", description = "Generates a translated commit message based on the provided request information." ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Successfully generated commit translation", + content = @Content(mediaType = "text/plain", schema = @Schema(type = "string"))), + @ApiResponse(responseCode = "400", description = "Bad request, invalid input data", + content = @Content(mediaType = "application/json")), + @ApiResponse(responseCode = "500", description = "Internal server error", + content = @Content(mediaType = "application/json")) + }) @PostMapping("/craft") public String generateCommit( + @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit translation request data", + required = true, + content = @Content(schema = @Schema(implementation = CommitTranslateRequest.class))) @RequestBody CommitTranslateRequest commitTranslateRequest) { return commitTranslateService.generateTranslateCommit( commitTranslateRequest.major(), diff --git a/src/main/java/pl/commit/craft/flow/CommitFlowController.java b/src/main/java/pl/commit/craft/flow/CommitFlowController.java index edd024e..9a54082 100644 --- a/src/main/java/pl/commit/craft/flow/CommitFlowController.java +++ b/src/main/java/pl/commit/craft/flow/CommitFlowController.java @@ -1,6 +1,11 @@ package pl.commit.craft.flow; 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 io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; @@ -9,6 +14,7 @@ @RestController @RequestMapping("/api/v1/commit-flow") +@Tag(name = "Commit Flow Controller", description = "Flow commit") public class CommitFlowController { private final CommitTranslateService commitTranslateService; @@ -21,8 +27,20 @@ public CommitFlowController(CommitTranslateService commitTranslateService) { summary = "Generate a commit message based on the provided commit flow data", description = "This endpoint receives commit flow details and generates the corresponding commit message." ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Successfully generated commit message", + content = @Content(mediaType = "text/plain", schema = @Schema(type = "string"))), + @ApiResponse(responseCode = "400", description = "Bad request, invalid input data", + content = @Content(mediaType = "application/json")), + @ApiResponse(responseCode = "500", description = "Internal server error", + content = @Content(mediaType = "application/json")) + }) @PostMapping("/craft") - public String generateCommit(@RequestBody CommitFlowRequest commitFlowRequest) { + public String generateCommit( + @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit flow request data", + required = true, + content = @Content(schema = @Schema(implementation = CommitFlowRequest.class))) + @RequestBody CommitFlowRequest commitFlowRequest) { return commitTranslateService.generateFlowCommit( commitFlowRequest.major(), commitFlowRequest.type(), diff --git a/src/main/java/pl/commit/craft/template/CommitCraftTemplateController.java b/src/main/java/pl/commit/craft/template/CommitCraftTemplateController.java index 305e3bc..2a11c52 100644 --- a/src/main/java/pl/commit/craft/template/CommitCraftTemplateController.java +++ b/src/main/java/pl/commit/craft/template/CommitCraftTemplateController.java @@ -1,7 +1,12 @@ package pl.commit.craft.template; 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.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.responses.ApiResponses; +import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; @@ -14,6 +19,7 @@ @RestController @RequestMapping("/api/v1/craft-template") @RequiredArgsConstructor +@Tag(name = "Commit Template Controller", description = "Management template commit model") public class CommitCraftTemplateController { private final CommitTemplateService commitTemplateService; @@ -22,6 +28,11 @@ public class CommitCraftTemplateController { summary = "Get all commit templates", description = "Fetches a list of all available commit craft templates." ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Successfully fetched templates", + content = @Content(mediaType = "application/json", + schema = @Schema(implementation = CommitCraftTemplate.class))) + }) @GetMapping("/all") public ResponseEntity> getAllTemplates() throws IOException { List templates = commitTemplateService.getAllTemplates(); @@ -30,14 +41,19 @@ public ResponseEntity> getAllTemplates() throws IOExce @Operation( summary = "Create a dedicated commit template", - description = "Creates a new dedicated commit template if the pattern and model scope are valid.", - responses = { - @ApiResponse(responseCode = "201", description = "Template created successfully"), - @ApiResponse(responseCode = "400", description = "Invalid template format or template already exists") - } + description = "Creates a new dedicated commit template if the pattern and model scope are valid." ) + @ApiResponses({ + @ApiResponse(responseCode = "201", description = "Template created successfully", + content = @Content(mediaType = "application/json")), + @ApiResponse(responseCode = "400", description = "Invalid template format or template already exists", + content = @Content(mediaType = "application/json")) + }) @PostMapping("/dedicated") - public ResponseEntity> createDedicatedTemplate(@RequestBody CommitCraftTemplate template) throws IOException { + public ResponseEntity> createDedicatedTemplate( + @RequestBody(description = "Commit template data", required = true, + content = @Content(schema = @Schema(implementation = CommitCraftTemplate.class))) + @org.springframework.web.bind.annotation.RequestBody CommitCraftTemplate template) throws IOException { TemplateOperationResult result = commitTemplateService.createDedicatedTemplate(template); if (result.success()) { @@ -53,11 +69,12 @@ public ResponseEntity> createDedicatedTemplate(@RequestBody @Operation( summary = "Remove a commit template", - description = "Removes a dedicated commit template by name.", - responses = { - @ApiResponse(responseCode = "200", description = "Template removed successfully") - } + description = "Removes a dedicated commit template by name." ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Template removed successfully", + content = @Content(mediaType = "text/plain")) + }) @DeleteMapping("/removed/{name}") public ResponseEntity addTemplate(@PathVariable("name") String name) throws IOException { commitTemplateService.removeDedicatedTemplate(name); @@ -66,11 +83,12 @@ public ResponseEntity addTemplate(@PathVariable("name") String name) thr @Operation( summary = "Generate commit template JSON", - description = "Generates a JSON representation of the commit template based on its name.", - responses = { - @ApiResponse(responseCode = "200", description = "JSON generated successfully") - } + description = "Generates a JSON representation of the commit template based on its name." ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "JSON generated successfully", + content = @Content(mediaType = "application/json")) + }) @PostMapping("/generate-json/{name}") public Map generateJson(@PathVariable String name) throws IOException { CommitCraftJson commitCraftJson = commitTemplateService.prepareJsonByModel(name); diff --git a/src/main/java/pl/commit/craft/template/generate/CommitTemplateGenerateController.java b/src/main/java/pl/commit/craft/template/generate/CommitTemplateGenerateController.java index 2d70536..39dc0fb 100644 --- a/src/main/java/pl/commit/craft/template/generate/CommitTemplateGenerateController.java +++ b/src/main/java/pl/commit/craft/template/generate/CommitTemplateGenerateController.java @@ -1,6 +1,13 @@ package pl.commit.craft.template.generate; import com.fasterxml.jackson.databind.JsonNode; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +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 io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; @@ -10,17 +17,56 @@ @RestController @RequestMapping("api/v1/craft-template") @RequiredArgsConstructor +@Tag( + name = "Commit Template Generation", + description = "API for generating commit messages based on predefined templates." +) public class CommitTemplateGenerateController { private final CommitTemplateGenerateService service; + @Operation( + summary = "Generate commit message", + description = "Generates a commit message based on a specified template and commit data." + ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Commit message generated successfully", + content = @Content(mediaType = "text/plain")), + @ApiResponse(responseCode = "400", description = "Invalid request data", + content = @Content(mediaType = "application/json")), + @ApiResponse(responseCode = "500", description = "Server error during commit generation", + content = @Content(mediaType = "application/json")) + }) @PostMapping("/generate") - public ResponseEntity generateCommit(@RequestParam String templateName, @RequestBody JsonNode commitData) throws IOException { + public ResponseEntity generateCommit( + @Parameter(description = "Name of the commit template", required = true) + @RequestParam String templateName, + @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit data as JSON model", required = true, + content = @Content(schema = @Schema(implementation = JsonNode.class))) + @RequestBody JsonNode commitData) throws IOException { String commitMessage = service.generateCommit(templateName, commitData); return ResponseEntity.ok(commitMessage); } + + @Operation( + summary = "Generate dedicated commit message", + description = "Generates a commit message using a dedicated template with provided commit data." + ) + @ApiResponses({ + @ApiResponse(responseCode = "200", description = "Commit message generated successfully", + content = @Content(mediaType = "text/plain")), + @ApiResponse(responseCode = "400", description = "Invalid request data", + content = @Content(mediaType = "application/json")), + @ApiResponse(responseCode = "500", description = "Server error during commit generation", + content = @Content(mediaType = "application/json")) + }) @PostMapping("/generate-dedicated") - public ResponseEntity generateDedicatedCommit(@RequestParam String templateName, @RequestBody JsonNode commitData) throws IOException { + public ResponseEntity generateDedicatedCommit( + @Parameter(description = "Name of the dedicated commit template", required = true) + @RequestParam String templateName, + @io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit data as JSON", required = true, + content = @Content(schema = @Schema(implementation = JsonNode.class))) + @org.springframework.web.bind.annotation.RequestBody JsonNode commitData) throws IOException { String commitMessage = service.generateDedicatedCommit(templateName, commitData); return ResponseEntity.ok(commitMessage); } diff --git a/src/main/resources/templates/dedicated-meta-schema.json b/src/main/resources/templates/dedicated-meta-schema.json index 83f352c..02c2457 100644 --- a/src/main/resources/templates/dedicated-meta-schema.json +++ b/src/main/resources/templates/dedicated-meta-schema.json @@ -1,14 +1 @@ -{ - "dedicated" : [ { - "name" : "apilia-project", - "description" : "Dedykowany dla projektu coś tam", - "pattern" : "{ticket_id} {type}({scope}):{message}-{details}", - "model" : { - "ticket_id" : "Numer powiązanego zadania w JIRA", - "type" : [ "feat", "fix", "junk", "chore", "test" ], - "scope" : "[moduł lub komponent]", - "message" : "Krótki opis zmiany", - "details" : "Szczegóły zmian w treści commit message" - } - } ] -} \ No newline at end of file +{"dedicated":[]} \ No newline at end of file