Update some documentation for the API.

pledger-io · Oct 1, 2024 · 47d390a · 47d390a
1 parent 74a76fe
commit 47d390a
Show file tree

Hide file tree

Showing 10 changed files with 18 additions and 44 deletions.
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -31,13 +31,11 @@ subprojects {
     }
 
     publishing {
-        if (project.name != "fintrack-api") {
-            publications {
-                create<MavenPublication>("maven") {
-                    groupId = "com.jongsoft.finance"
-                    version = System.getProperty("version")
-                    from(components["java"])
-                }
+        publications {
+            create<MavenPublication>("maven") {
+                groupId = "com.jongsoft.finance"
+                version = System.getProperty("version")
+                from(components["java"])
             }
         }
 

diff --git a/fintrack-api/build.gradle.kts b/fintrack-api/build.gradle.kts
@@ -1,6 +1,5 @@
 plugins {
     id("io.micronaut.application")
-    id("org.openapi.generator")
 }
 
 application {
@@ -12,14 +11,6 @@ micronaut {
     testRuntime("junit5")
 }
 
-openApiGenerate {
-    inputSpec.set(layout.buildDirectory.dir("classes/java/main/META-INF/swagger").get().file("pledger-2.0.0.yml").toString())
-    outputDir.set(layout.buildDirectory.dir("asciidoc").get().toString())
-    cleanupOutput.set(true)
-    generatorName.set("asciidoc")
-    skipValidateSpec.set(true)
-}
-
 val integration by sourceSets.creating
 
 configurations[integration.implementationConfigurationName].extendsFrom(configurations.testImplementation.get())
@@ -43,28 +34,6 @@ tasks.check {
     dependsOn("itTest")
 }
 
-tasks.withType<JavaCompile> {
-    finalizedBy(tasks.getByName("openApiGenerate"))
-}
-
-configurations {
-    create("api-docs")
-}
-
-val apiArtifact = artifacts.add("api-docs", layout.buildDirectory.file("asciidoc/index.adoc")) {
-    type = "asciidoc"
-    builtBy(tasks.getByName("openApiGenerate"))
-}
-
-publishing.publications {
-    create<MavenPublication>("maven") {
-        groupId = "com.jongsoft.finance"
-        version = System.getProperty("version")
-        from(components["java"])
-        artifact(apiArtifact)
-    }
-}
-
 dependencies {
     annotationProcessor(mn.micronaut.openapi.asProvider())
     annotationProcessor(mn.micronaut.http.validation)

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/Application.java b/fintrack-api/src/main/java/com/jongsoft/finance/Application.java
@@ -13,6 +13,7 @@
         info = @Info(
                 title = "Pledger",
                 version = "2.0.0",
+                description = "Pledger.io is a self-hosted personal finance application that helps you track your income and expenses.",
                 license = @License(name = "MIT", url = "https://opensource.org/licenses/MIT"),
                 contact = @Contact(
                         name = "Jong Soft Development",

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/ApiDefaults.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/ApiDefaults.java
@@ -14,7 +14,7 @@
 
 @Documented
 @Retention(RUNTIME)
-@Target({ElementType.METHOD})
+@Target({ElementType.METHOD, ElementType.TYPE})
 @ApiResponse(
         responseCode = "404",
         content = @Content(schema = @Schema(implementation = JsonError.class)),

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/StaticResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/StaticResource.java
@@ -30,6 +30,7 @@ public class StaticResource {
     ResourceResolver res;
 
     @Get
+    @Operation(hidden = true)
     public HttpResponse<?> index() throws URISyntaxException {
         return HttpResponse.redirect(new URI("/ui/dashboard"));
     }

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountEditResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountEditResource.java
@@ -21,6 +21,7 @@
 
 import java.math.BigDecimal;
 
+@ApiDefaults
 @Controller("/api/accounts/{accountId}")
 @Tag(name = "Account information")
 @Secured(SecurityRule.IS_AUTHENTICATED)
@@ -147,7 +148,6 @@ void delete(@PathVariable long accountId) {
             summary = "Create saving goal",
             description = "Creates a saving goal into the account, only valid for accounts of types SAVINGS and JOINED_SAVINGS"
     )
-    @ApiDefaults
     AccountResponse createSavingGoal(
             @PathVariable long accountId,
             @Body @Valid AccountSavingGoalCreateRequest request) {
@@ -170,7 +170,6 @@ AccountResponse createSavingGoal(
             summary = "Adjust Saving Goal",
             description = "Adjust a saving goal already attached to the savings account."
     )
-    @ApiDefaults
     AccountResponse adjustSavingGoal(
             @PathVariable long accountId,
             @PathVariable long savingId,
@@ -194,7 +193,6 @@ AccountResponse adjustSavingGoal(
             summary = "Reserve Saving Goal",
             description = "Reserve money from the account towards the saving goal."
     )
-    @ApiDefaults
     AccountResponse reservationForSavingGoal(
             @PathVariable long accountId,
             @PathVariable long savingId,
@@ -218,7 +216,6 @@ AccountResponse reservationForSavingGoal(
             summary = "Delete saving goal",
             description = "Removes a saving goal from the account."
     )
-    @ApiDefaults
     void deleteSavingGoal(@PathVariable long accountId, @PathVariable long savingId) {
         accountProvider.lookup(accountId)
                 .ifPresent(account ->

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountResource.java
@@ -5,6 +5,7 @@
 import com.jongsoft.finance.providers.AccountProvider;
 import com.jongsoft.finance.providers.AccountTypeProvider;
 import com.jongsoft.finance.providers.SettingProvider;
+import com.jongsoft.finance.rest.ApiDefaults;
 import com.jongsoft.finance.rest.model.AccountResponse;
 import com.jongsoft.finance.rest.model.ResultPageResponse;
 import com.jongsoft.finance.security.AuthenticationRoles;
@@ -22,6 +23,7 @@
 
 import java.util.List;
 
+@ApiDefaults
 @Controller("/api/accounts")
 @Tag(name = "Account information")
 @Secured(AuthenticationRoles.IS_AUTHENTICATED)

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountTopResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountTopResource.java
@@ -3,6 +3,7 @@
 import com.jongsoft.finance.factory.FilterFactory;
 import com.jongsoft.finance.providers.AccountProvider;
 import com.jongsoft.finance.providers.SettingProvider;
+import com.jongsoft.finance.rest.ApiDefaults;
 import com.jongsoft.finance.rest.DateFormat;
 import com.jongsoft.finance.security.AuthenticationRoles;
 import com.jongsoft.lang.Collections;
@@ -17,6 +18,7 @@
 import java.time.LocalDate;
 import java.util.List;
 
+@ApiDefaults
 @Controller("/api/accounts/top")
 @Tag(name = "Account information")
 @Secured(AuthenticationRoles.IS_AUTHENTICATED)

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountTransactionResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountTransactionResource.java
@@ -30,7 +30,9 @@
 
 import java.util.function.Consumer;
 
-@Tag(name = "Transactions")
+@Tag(
+        name = "Account Transactions",
+        description = "Operations on transactions based on a given account.")
 @Secured(AuthenticationRoles.IS_AUTHENTICATED)
 @Controller("/api/accounts/{accountId}/transactions")
 public class AccountTransactionResource {

diff --git a/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountTypeResource.java b/fintrack-api/src/main/java/com/jongsoft/finance/rest/account/AccountTypeResource.java
@@ -1,6 +1,7 @@
 package com.jongsoft.finance.rest.account;
 
 import com.jongsoft.finance.providers.AccountTypeProvider;
+import com.jongsoft.finance.rest.ApiDefaults;
 import com.jongsoft.finance.security.AuthenticationRoles;
 import io.micronaut.http.annotation.Controller;
 import io.micronaut.http.annotation.Get;
@@ -11,6 +12,7 @@
 
 import java.util.List;
 
+@ApiDefaults
 @Singleton
 @Tag(name = "Account information")
 @Controller("/api/account-types")