Skip to content

Commit c69485e

Browse files
kamarroskamarros
authored
Merge pull request #43 from KamilAdd-Byte/swagger---describe-more-endpoints
doc: added swagger documentation for api.
2 parents 6e90295 + 8954c6a commit c69485e

File tree

5 files changed

+117
-31
lines changed

5 files changed

+117
-31
lines changed

‎src/main/java/pl/commit/craft/controller/CommitTranslateController.java‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,17 @@
11
package pl.commit.craft.controller;
22

33
import io.swagger.v3.oas.annotations.Operation;
4+
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.Schema;
6+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
7+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
8+
import io.swagger.v3.oas.annotations.tags.Tag;
49
import org.springframework.web.bind.annotation.*;
510
import pl.commit.craft.service.CommitTranslateService;
611

712
@RestController
813
@RequestMapping("/api/v1/commit-translate")
14+
@Tag(name = "Commit Translation Controller", description = "Translate commit wit deepl api")
915
public class CommitTranslateController {
1016

1117
private final CommitTranslateService commitTranslateService;
@@ -18,8 +24,19 @@ public CommitTranslateController(CommitTranslateService commitTranslateService)
1824
summary = "Generate commit translation",
1925
description = "Generates a translated commit message based on the provided request information."
2026
)
27+
@ApiResponses({
28+
@ApiResponse(responseCode = "200", description = "Successfully generated commit translation",
29+
content = @Content(mediaType = "text/plain", schema = @Schema(type = "string"))),
30+
@ApiResponse(responseCode = "400", description = "Bad request, invalid input data",
31+
content = @Content(mediaType = "application/json")),
32+
@ApiResponse(responseCode = "500", description = "Internal server error",
33+
content = @Content(mediaType = "application/json"))
34+
})
2135
@PostMapping("/craft")
2236
public String generateCommit(
37+
@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit translation request data",
38+
required = true,
39+
content = @Content(schema = @Schema(implementation = CommitTranslateRequest.class)))
2340
@RequestBody CommitTranslateRequest commitTranslateRequest) {
2441
return commitTranslateService.generateTranslateCommit(
2542
commitTranslateRequest.major(),

‎src/main/java/pl/commit/craft/flow/CommitFlowController.java‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
package pl.commit.craft.flow;
22

33
import io.swagger.v3.oas.annotations.Operation;
4+
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.Schema;
6+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
7+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
8+
import io.swagger.v3.oas.annotations.tags.Tag;
49
import org.springframework.web.bind.annotation.PostMapping;
510
import org.springframework.web.bind.annotation.RequestBody;
611
import org.springframework.web.bind.annotation.RequestMapping;
@@ -9,6 +14,7 @@
914

1015
@RestController
1116
@RequestMapping("/api/v1/commit-flow")
17+
@Tag(name = "Commit Flow Controller", description = "Flow commit")
1218
public class CommitFlowController {
1319

1420
private final CommitTranslateService commitTranslateService;
@@ -21,8 +27,20 @@ public CommitFlowController(CommitTranslateService commitTranslateService) {
2127
summary = "Generate a commit message based on the provided commit flow data",
2228
description = "This endpoint receives commit flow details and generates the corresponding commit message."
2329
)
30+
@ApiResponses({
31+
@ApiResponse(responseCode = "200", description = "Successfully generated commit message",
32+
content = @Content(mediaType = "text/plain", schema = @Schema(type = "string"))),
33+
@ApiResponse(responseCode = "400", description = "Bad request, invalid input data",
34+
content = @Content(mediaType = "application/json")),
35+
@ApiResponse(responseCode = "500", description = "Internal server error",
36+
content = @Content(mediaType = "application/json"))
37+
})
2438
@PostMapping("/craft")
25-
public String generateCommit(@RequestBody CommitFlowRequest commitFlowRequest) {
39+
public String generateCommit(
40+
@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit flow request data",
41+
required = true,
42+
content = @Content(schema = @Schema(implementation = CommitFlowRequest.class)))
43+
@RequestBody CommitFlowRequest commitFlowRequest) {
2644
return commitTranslateService.generateFlowCommit(
2745
commitFlowRequest.major(),
2846
commitFlowRequest.type(),

‎src/main/java/pl/commit/craft/template/CommitCraftTemplateController.java‎

Lines changed: 32 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
package pl.commit.craft.template;
22

33
import io.swagger.v3.oas.annotations.Operation;
4+
import io.swagger.v3.oas.annotations.media.Content;
5+
import io.swagger.v3.oas.annotations.media.Schema;
6+
import io.swagger.v3.oas.annotations.parameters.RequestBody;
47
import io.swagger.v3.oas.annotations.responses.ApiResponse;
8+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
9+
import io.swagger.v3.oas.annotations.tags.Tag;
510
import lombok.RequiredArgsConstructor;
611
import org.springframework.http.HttpStatus;
712
import org.springframework.http.ResponseEntity;
@@ -14,6 +19,7 @@
1419
@RestController
1520
@RequestMapping("/api/v1/craft-template")
1621
@RequiredArgsConstructor
22+
@Tag(name = "Commit Template Controller", description = "Management template commit model")
1723
public class CommitCraftTemplateController {
1824

1925
private final CommitTemplateService commitTemplateService;
@@ -22,6 +28,11 @@ public class CommitCraftTemplateController {
2228
summary = "Get all commit templates",
2329
description = "Fetches a list of all available commit craft templates."
2430
)
31+
@ApiResponses({
32+
@ApiResponse(responseCode = "200", description = "Successfully fetched templates",
33+
content = @Content(mediaType = "application/json",
34+
schema = @Schema(implementation = CommitCraftTemplate.class)))
35+
})
2536
@GetMapping("/all")
2637
public ResponseEntity<List<CommitCraftTemplate>> getAllTemplates() throws IOException {
2738
List<CommitCraftTemplate> templates = commitTemplateService.getAllTemplates();
@@ -30,14 +41,19 @@ public ResponseEntity<List<CommitCraftTemplate>> getAllTemplates() throws IOExce
3041

3142
@Operation(
3243
summary = "Create a dedicated commit template",
33-
description = "Creates a new dedicated commit template if the pattern and model scope are valid.",
34-
responses = {
35-
@ApiResponse(responseCode = "201", description = "Template created successfully"),
36-
@ApiResponse(responseCode = "400", description = "Invalid template format or template already exists")
37-
}
44+
description = "Creates a new dedicated commit template if the pattern and model scope are valid."
3845
)
46+
@ApiResponses({
47+
@ApiResponse(responseCode = "201", description = "Template created successfully",
48+
content = @Content(mediaType = "application/json")),
49+
@ApiResponse(responseCode = "400", description = "Invalid template format or template already exists",
50+
content = @Content(mediaType = "application/json"))
51+
})
3952
@PostMapping("/dedicated")
40-
public ResponseEntity<Map<String, String>> createDedicatedTemplate(@RequestBody CommitCraftTemplate template) throws IOException {
53+
public ResponseEntity<Map<String, String>> createDedicatedTemplate(
54+
@RequestBody(description = "Commit template data", required = true,
55+
content = @Content(schema = @Schema(implementation = CommitCraftTemplate.class)))
56+
@org.springframework.web.bind.annotation.RequestBody CommitCraftTemplate template) throws IOException {
4157
TemplateOperationResult result = commitTemplateService.createDedicatedTemplate(template);
4258

4359
if (result.success()) {
@@ -53,11 +69,12 @@ public ResponseEntity<Map<String, String>> createDedicatedTemplate(@RequestBody
5369

5470
@Operation(
5571
summary = "Remove a commit template",
56-
description = "Removes a dedicated commit template by name.",
57-
responses = {
58-
@ApiResponse(responseCode = "200", description = "Template removed successfully")
59-
}
72+
description = "Removes a dedicated commit template by name."
6073
)
74+
@ApiResponses({
75+
@ApiResponse(responseCode = "200", description = "Template removed successfully",
76+
content = @Content(mediaType = "text/plain"))
77+
})
6178
@DeleteMapping("/removed/{name}")
6279
public ResponseEntity<String> addTemplate(@PathVariable("name") String name) throws IOException {
6380
commitTemplateService.removeDedicatedTemplate(name);
@@ -66,11 +83,12 @@ public ResponseEntity<String> addTemplate(@PathVariable("name") String name) thr
6683

6784
@Operation(
6885
summary = "Generate commit template JSON",
69-
description = "Generates a JSON representation of the commit template based on its name.",
70-
responses = {
71-
@ApiResponse(responseCode = "200", description = "JSON generated successfully")
72-
}
86+
description = "Generates a JSON representation of the commit template based on its name."
7387
)
88+
@ApiResponses({
89+
@ApiResponse(responseCode = "200", description = "JSON generated successfully",
90+
content = @Content(mediaType = "application/json"))
91+
})
7492
@PostMapping("/generate-json/{name}")
7593
public Map<String, Object> generateJson(@PathVariable String name) throws IOException {
7694
CommitCraftJson commitCraftJson = commitTemplateService.prepareJsonByModel(name);

‎src/main/java/pl/commit/craft/template/generate/CommitTemplateGenerateController.java‎

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
package pl.commit.craft.template.generate;
22

33
import com.fasterxml.jackson.databind.JsonNode;
4+
import io.swagger.v3.oas.annotations.Operation;
5+
import io.swagger.v3.oas.annotations.Parameter;
6+
import io.swagger.v3.oas.annotations.media.Content;
7+
import io.swagger.v3.oas.annotations.media.Schema;
8+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
9+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
10+
import io.swagger.v3.oas.annotations.tags.Tag;
411
import lombok.RequiredArgsConstructor;
512
import org.springframework.http.ResponseEntity;
613
import org.springframework.web.bind.annotation.*;
@@ -10,17 +17,56 @@
1017
@RestController
1118
@RequestMapping("api/v1/craft-template")
1219
@RequiredArgsConstructor
20+
@Tag(
21+
name = "Commit Template Generation",
22+
description = "API for generating commit messages based on predefined templates."
23+
)
1324
public class CommitTemplateGenerateController {
1425
private final CommitTemplateGenerateService service;
1526

27+
@Operation(
28+
summary = "Generate commit message",
29+
description = "Generates a commit message based on a specified template and commit data."
30+
)
31+
@ApiResponses({
32+
@ApiResponse(responseCode = "200", description = "Commit message generated successfully",
33+
content = @Content(mediaType = "text/plain")),
34+
@ApiResponse(responseCode = "400", description = "Invalid request data",
35+
content = @Content(mediaType = "application/json")),
36+
@ApiResponse(responseCode = "500", description = "Server error during commit generation",
37+
content = @Content(mediaType = "application/json"))
38+
})
1639
@PostMapping("/generate")
17-
public ResponseEntity<String> generateCommit(@RequestParam String templateName, @RequestBody JsonNode commitData) throws IOException {
40+
public ResponseEntity<String> generateCommit(
41+
@Parameter(description = "Name of the commit template", required = true)
42+
@RequestParam String templateName,
43+
@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit data as JSON model", required = true,
44+
content = @Content(schema = @Schema(implementation = JsonNode.class)))
45+
@RequestBody JsonNode commitData) throws IOException {
1846
String commitMessage = service.generateCommit(templateName, commitData);
1947
return ResponseEntity.ok(commitMessage);
2048
}
2149

50+
51+
@Operation(
52+
summary = "Generate dedicated commit message",
53+
description = "Generates a commit message using a dedicated template with provided commit data."
54+
)
55+
@ApiResponses({
56+
@ApiResponse(responseCode = "200", description = "Commit message generated successfully",
57+
content = @Content(mediaType = "text/plain")),
58+
@ApiResponse(responseCode = "400", description = "Invalid request data",
59+
content = @Content(mediaType = "application/json")),
60+
@ApiResponse(responseCode = "500", description = "Server error during commit generation",
61+
content = @Content(mediaType = "application/json"))
62+
})
2263
@PostMapping("/generate-dedicated")
23-
public ResponseEntity<String> generateDedicatedCommit(@RequestParam String templateName, @RequestBody JsonNode commitData) throws IOException {
64+
public ResponseEntity<String> generateDedicatedCommit(
65+
@Parameter(description = "Name of the dedicated commit template", required = true)
66+
@RequestParam String templateName,
67+
@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Commit data as JSON", required = true,
68+
content = @Content(schema = @Schema(implementation = JsonNode.class)))
69+
@org.springframework.web.bind.annotation.RequestBody JsonNode commitData) throws IOException {
2470
String commitMessage = service.generateDedicatedCommit(templateName, commitData);
2571
return ResponseEntity.ok(commitMessage);
2672
}

‎src/main/resources/templates/dedicated-meta-schema.json‎

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1 @@
1-
{
2-
"dedicated" : [ {
3-
"name" : "apilia-project",
4-
"description" : "Dedykowany dla projektu coś tam",
5-
"pattern" : "{ticket_id} {type}({scope}):{message}-{details}",
6-
"model" : {
7-
"ticket_id" : "Numer powiązanego zadania w JIRA",
8-
"type" : [ "feat", "fix", "junk", "chore", "test" ],
9-
"scope" : "[moduł lub komponent]",
10-
"message" : "Krótki opis zmiany",
11-
"details" : "Szczegóły zmian w treści commit message"
12-
}
13-
} ]
14-
}
1+
{"dedicated":[]}

0 commit comments

Comments
 (0)