feat(java-sdk): add maven central documentation to service READMEs (#194)

relates to STACKITSDK-207

Author: rubenhoenle

openapi-generator-config-java.yml

@@ -6,7 +6,7 @@ additionalProperties:
   developerEmail: [email protected]
   developerOrganization: STACKIT
   developerOrganizationUrl: https://www.stackit.de
-  groupId: cloud.stackit
+  groupId: cloud.stackit.sdk
   hideGenerationTimestamp: true
   licenseName: Apache License 2.0
   licenseUrl: http://www.apache.org/licenses/

scripts/generate-sdk/.openapi-generator-ignore-java

@@ -15,6 +15,9 @@ build.sbt
 # there's no content in it
 gradle.properties
 
+# content isn't needed
+settings.gradle
+
 # gradle wrapper (we don't need it because we use the generated projects as gradle subprojects)
 gradlew.bat
 gradlew
@@ -27,4 +30,4 @@ gradle/**
 **/auth/**
 
 # Service Configuration is not required. It only stores a defaultApiClient
-**/Configuration.java
+**/Configuration.java

scripts/generate-sdk/languages/java.sh

@@ -51,31 +51,31 @@ generate_java_sdk() {
     fi
 
     # Clone SDK repo
-    if [ -d ${SDK_REPO_LOCAL_PATH} ]; then
+    if [ -d "${SDK_REPO_LOCAL_PATH}" ]; then
         echo "Old SDK repo clone was found, it will be removed."
-        rm -rf ${SDK_REPO_LOCAL_PATH}
+        rm -rf "${SDK_REPO_LOCAL_PATH}"
     fi
-    git clone --quiet -b ${SDK_BRANCH} ${SDK_REPO_URL} ${SDK_REPO_LOCAL_PATH}
+    git clone --quiet -b "${SDK_BRANCH}" "${SDK_REPO_URL}" "${SDK_REPO_LOCAL_PATH}"
 
     # Backup of the current state of the SDK services dir (services/)
     sdk_services_backup_dir=$(mktemp -d)
-    if [[ ! ${sdk_services_backup_dir} || -d {sdk_services_backup_dir} ]]; then
+    if [[ ! "${sdk_services_backup_dir}" || -d {sdk_services_backup_dir} ]]; then
         echo "! Unable to create temporary directory"
         exit 1
     fi
     cleanup() {
-        rm -rf ${sdk_services_backup_dir}
+        rm -rf "${sdk_services_backup_dir}"
     }
-    cp -a "${SERVICES_FOLDER}/." ${sdk_services_backup_dir}
+    cp -a "${SERVICES_FOLDER}/." "${sdk_services_backup_dir}"
 
     # Cleanup after we are done
     trap cleanup EXIT
 
     # Remove old contents of services dir (services/)
-    rm -rf ${SERVICES_FOLDER}
+    rm -rf "${SERVICES_FOLDER}"
 
     # Generate SDK for each service
-    for service_json in ${ROOT_DIR}/oas/*.json; do
+    for service_json in "${ROOT_DIR}"/oas/*.json; do
         service="${service_json##*/}"
         service="${service%.json}"
 
@@ -97,29 +97,29 @@ generate_java_sdk() {
             continue
         fi
 
-        if grep -E "^$service$" ${ROOT_DIR}/blacklist.txt; then
+        if grep -E "^$service$" "${ROOT_DIR}/blacklist.txt"; then
             echo "Skipping blacklisted service ${service}"
             continue
         fi
 
         echo ">> Generating \"${service}\" service..."
-        cd ${ROOT_DIR}
+        cd "${ROOT_DIR}"
 
         mkdir -p "${SERVICES_FOLDER}/${service}/"
         cp "${ROOT_DIR}/scripts/generate-sdk/.openapi-generator-ignore-java" "${SERVICES_FOLDER}/${service}/.openapi-generator-ignore"
 
-        SERVICE_DESCRIPTION=$(cat ${service_json} | jq .info.title --raw-output)
+        SERVICE_DESCRIPTION=$(cat "${service_json}" | jq .info.title --raw-output)
 
         # Run the generator
-        java -Dlog.level=${GENERATOR_LOG_LEVEL} -jar ${jar_path} generate \
+        java -Dlog.level="${GENERATOR_LOG_LEVEL}" -jar "${GENERATOR_JAR_PATH}" generate \
             --generator-name java \
             --input-spec "${service_json}" \
             --output "${SERVICES_FOLDER}/${service}" \
-            --git-host ${GIT_HOST} \
-            --git-user-id ${GIT_USER_ID} \
-            --git-repo-id ${GIT_REPO_ID} \
+            --git-host "${GIT_HOST}" \
+            --git-user-id "${GIT_USER_ID}" \
+            --git-repo-id "${GIT_REPO_ID}" \
             --global-property apis,models,modelTests=false,modelDocs=false,apiDocs=false,apiTests=false,supportingFiles \
-            --additional-properties=artifactId="stackit-sdk-${service}",artifactDescription="${SERVICE_DESCRIPTION}",invokerPackage="cloud.stackit.sdk.${service}",modelPackage="cloud.stackit.sdk.${service}.model",apiPackage="cloud.stackit.sdk.${service}.api",serviceName="${service_pascal_case},serviceId=${service}"  >/dev/null \
+            --additional-properties="artifactId=${service},artifactDescription=${SERVICE_DESCRIPTION},invokerPackage=cloud.stackit.sdk.${service},modelPackage=cloud.stackit.sdk.${service}.model,apiPackage=cloud.stackit.sdk.${service}.api,serviceName=${service_pascal_case}"  >/dev/null \
   	        --http-user-agent stackit-sdk-java/"${service}" \
             --config openapi-generator-config-java.yml
 
@@ -135,27 +135,27 @@ generate_java_sdk() {
         rm -r "${SERVICES_FOLDER}/${service}/.openapi-generator/"
 
         # If the service has a CHANGELOG file, move it inside the service folder
-        if [ -f ${sdk_services_backup_dir}/${service}/CHANGELOG.md ]; then
+        if [ -f "${sdk_services_backup_dir}/${service}/CHANGELOG.md" ]; then
             echo "Found ${service} \"CHANGELOG\" file"
-            cp -r ${sdk_services_backup_dir}/${service}/CHANGELOG.md ${SERVICES_FOLDER}/${service}/CHANGELOG.md
+            cp -r "${sdk_services_backup_dir}/${service}/CHANGELOG.md" "${SERVICES_FOLDER}/${service}/CHANGELOG.md"
         fi
 
         # If the service has a LICENSE file, move it inside the service folder
-        if [ -f ${sdk_services_backup_dir}/${service}/LICENSE.md ]; then
+        if [ -f "${sdk_services_backup_dir}/${service}/LICENSE.md" ]; then
             echo "Found ${service} \"LICENSE\" file"
-            cp -r ${sdk_services_backup_dir}/${service}/LICENSE.md ${SERVICES_FOLDER}/${service}/LICENSE.md
+            cp -r "${sdk_services_backup_dir}/${service}/LICENSE.md" "${SERVICES_FOLDER}/${service}/LICENSE.md"
         fi
 
         # If the service has a NOTICE file, move it inside the service folder
-        if [ -f ${sdk_services_backup_dir}/${service}/NOTICE.txt ]; then
+        if [ -f "${sdk_services_backup_dir}/${service}/NOTICE.txt" ]; then
             echo "Found ${service} \"NOTICE\" file"
-            cp -r ${sdk_services_backup_dir}/${service}/NOTICE.txt ${SERVICES_FOLDER}/${service}/NOTICE.txt
+            cp -r "${sdk_services_backup_dir}/${service}/NOTICE.txt" "${SERVICES_FOLDER}/${service}/NOTICE.txt"
         fi
 
         # If the service has a VERSION file, move it inside the service folder
-        if [ -f ${sdk_services_backup_dir}/${service}/VERSION ]; then
+        if [ -f "${sdk_services_backup_dir}/${service}/VERSION" ]; then
             echo "Found ${service} \"VERSION\" file"
-            cp -r ${sdk_services_backup_dir}/${service}/VERSION ${SERVICES_FOLDER}/${service}/VERSION
+            cp -r "${sdk_services_backup_dir}/${service}/VERSION" "${SERVICES_FOLDER}/${service}/VERSION"
         fi
 
     done

templates/java/README.mustache

@@ -1,6 +1,4 @@
-# {{artifactId}}
-
-{{appName}}
+# STACKIT Java SDK for {{appName}}
 
 - API version: {{appVersion}}
 
@@ -12,28 +10,9 @@ For more information, please visit [{{{infoUrl}}}]({{{infoUrl}}})
 
 This package is part of the STACKIT Java SDK. For additional information, please visit the [GitHub repository](https://{{gitHost}}/{{{gitUserId}}}/{{{gitRepoId}}}) of the SDK.
 
+## Installation from Maven Central (recommended)
 
-## Requirements
-
-Building the API client library requires:
-1. Java SDK (version 11 to 21 should be supported) installed on your system
-
-## Installation
-
-To install the API client library to your local Maven repository, simply execute:
-
-```shell
-./gradlew publishToMavenLocal
-```
-
-To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:
-
-```shell
-# TODO: follow up story
-# ./gradlew publishToMavenCentral
-```
-
-Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information.
+The release artifacts for this SDK submodule are available on [Maven Central](https://central.sonatype.com/artifact/{{groupId}}/{{artifactId}}).
 
 ### Maven users
 
@@ -54,59 +33,55 @@ Add this dependency to your project's build file:
 
 ```groovy
   repositories {
-    mavenCentral()     // Needed if the '{{{artifactId}}}' jar has been published to maven central.
-    mavenLocal()       // Needed if the '{{{artifactId}}}' jar has been published to the local maven repo.
+    mavenCentral()
   }
 
   dependencies {
      implementation "{{{groupId}}}:{{{artifactId}}}:<SDK_VERSION>"
   }
 ```
 
-### Others
+## Installation from local build
 
-At first generate the JAR by executing:
+Building the API client library requires:
+1. Java SDK (version 11 to 21 should be supported) installed on your system
+
+To install the API client library to your local Maven repository, simply execute:
 
 ```shell
-mvn clean package
+./gradlew services:{{artifactId}}:publishToMavenLocal
 ```
 
-Then manually install the following JARs:
+### Maven users
 
-- `target/{{{artifactId}}}-<SDK_VERSION>.jar`
-- `target/lib/*.jar`
+Add this dependency to your project's POM:
 
-{{#jersey2}}
-## Usage
+```xml
+<dependency>
+  <groupId>{{{groupId}}}</groupId>
+  <artifactId>{{{artifactId}}}</artifactId>
+  <version><SDK_VERSION></version>
+  <scope>compile</scope>
+</dependency>
+```
 
-To add a HTTP proxy for the API client, use `ClientConfig`:
-```java
-{{#apiInfo}}{{#apis}}{{#-first}}{{#operations}}{{#operation}}{{#-first}}
-import org.glassfish.jersey.apache.connector.ApacheConnectorProvider;
-import org.glassfish.jersey.client.ClientConfig;
-import org.glassfish.jersey.client.ClientProperties;
-import {{{invokerPackage}}}.*;
-import {{{package}}}.{{{classname}}};
+### Gradle users
 
-...
+Add this dependency to your project's build file:
 
-ApiClient defaultClient = Configuration.getDefaultApiClient();
-ClientConfig clientConfig = defaultClient.getClientConfig();
-clientConfig.connectorProvider(new ApacheConnectorProvider());
-clientConfig.property(ClientProperties.PROXY_URI, "http://proxy_url_here");
-clientConfig.property(ClientProperties.PROXY_USERNAME, "proxy_username");
-clientConfig.property(ClientProperties.PROXY_PASSWORD, "proxy_password");
-defaultClient.setClientConfig(clientConfig);
+```groovy
+  repositories {
+    mavenLocal()
+  }
 
-{{{classname}}} apiInstance = new {{{classname}}}(defaultClient);
-{{/-first}}{{/operation}}{{/operations}}{{/-first}}{{/apis}}{{/apiInfo}}
+  dependencies {
+     implementation "{{{groupId}}}:{{{artifactId}}}:<SDK_VERSION>"
+  }
 ```
 
-{{/jersey2}}
 ## Getting Started
 
-See the [{{serviceId}} examples]({{scmUrl}}/tree/main/examples/{{serviceId}}/src/main/java/cloud/stackit/sdk/{{serviceId}}/examples).
-
+See the [{{artifactId}} examples]({{scmUrl}}/tree/main/examples/{{artifactId}}/src/main/java/cloud/stackit/sdk/{{artifactId}}/examples).
 
 ## Recommendation