Add comments to production code (#10)

* Add comments to production code

* Fix lint issues

Author: cjaehnen

src/main/kotlin/io/opengood/autoconfig/openapidocs/Functions.kt

@@ -4,6 +4,16 @@ import io.swagger.v3.oas.models.Operation
 import io.swagger.v3.oas.models.PathItem
 import io.swagger.v3.oas.models.Paths
 
+/**
+ * Creates a Paths object from a list of path strings.
+ *
+ * This function takes a list of path strings and converts them into a Paths object
+ * that can be used in OpenAPI documentation. Each path is added as a PathItem with
+ * a GET operation.
+ *
+ * @param list List of path strings to convert
+ * @return Paths object containing all the paths from the list
+ */
 internal fun getPaths(list: List<String>): Paths {
     val paths = Paths()
     list.forEach { paths.addPathItem(it, PathItem().get(Operation())) }

src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt

@@ -14,12 +14,28 @@ import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty
 import org.springframework.boot.context.properties.EnableConfigurationProperties
 import org.springframework.context.annotation.Bean
 
+/**
+ * Spring Boot auto-configuration class for OpenAPI documentation.
+ *
+ * This class automatically configures OpenAPI documentation for a Spring Boot application
+ * based on the properties defined in OpenApiDocsProperties. It is enabled when the
+ * "openapi-docs.enabled" property is set to "true".
+ */
 @AutoConfiguration
 @ConditionalOnProperty("openapi-docs.enabled", havingValue = "true")
 @EnableConfigurationProperties(value = [OpenApiDocsProperties::class])
 class OpenApiDocsAutoConfiguration(
     private val properties: OpenApiDocsProperties,
 ) {
+    /**
+     * Creates and configures an OpenAPI bean based on the provided properties.
+     *
+     * This method sets up the OpenAPI documentation with information about the API,
+     * including title, description, version, contact information, license, and security
+     * settings if enabled.
+     *
+     * @return Configured OpenAPI instance
+     */
     @Bean
     fun openApi(): OpenAPI {
         log.info("Setup OpenAPI docs configuration")

src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/BearerFormat.kt

@@ -1,10 +1,21 @@
 package io.opengood.autoconfig.openapidocs.enumeration
 
+/**
+ * Enumeration of bearer token formats for OpenAPI security schemes.
+ *
+ * This enum defines the supported bearer token formats that can be used
+ * in OpenAPI security schemes, such as JWT.
+ */
 enum class BearerFormat(
     private val value: String,
 ) {
     JWT("JWT"),
     ;
 
+    /**
+     * Returns the string representation of the bearer format.
+     *
+     * @return String value of the bearer format
+     */
     override fun toString() = value
 }

src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Oauth2GrantType.kt

@@ -1,11 +1,22 @@
 package io.opengood.autoconfig.openapidocs.enumeration
 
+/**
+ * Enumeration of OAuth2 grant types for OpenAPI security schemes.
+ *
+ * This enum defines the supported OAuth2 grant types that can be used
+ * in OpenAPI security schemes, such as authorization code and client credentials.
+ */
 enum class Oauth2GrantType(
     private val value: String,
 ) {
     AUTHORIZATION_CODE("authorizationCode"),
     CLIENT_CREDENTIALS("clientCredentials"),
     ;
 
+    /**
+     * Returns the string representation of the OAuth2 grant type.
+     *
+     * @return String value of the OAuth2 grant type
+     */
     override fun toString() = value
 }

src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Scheme.kt

@@ -1,11 +1,22 @@
 package io.opengood.autoconfig.openapidocs.enumeration
 
+/**
+ * Enumeration of security schemes for OpenAPI security definitions.
+ *
+ * This enum defines the supported security schemes that can be used
+ * in OpenAPI security definitions, such as basic and bearer authentication.
+ */
 enum class Scheme(
     private val value: String,
 ) {
     BASIC("basic"),
     BEARER("bearer"),
     ;
 
+    /**
+     * Returns the string representation of the security scheme.
+     *
+     * @return String value of the security scheme
+     */
     override fun toString() = value
 }

src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Type.kt

@@ -3,14 +3,34 @@ package io.opengood.autoconfig.openapidocs.enumeration
 import io.swagger.v3.oas.models.security.SecurityScheme
 import java.util.Locale
 
+/**
+ * Enumeration of security types for OpenAPI security schemes.
+ *
+ * This enum defines the supported security types that can be used
+ * in OpenAPI security schemes, such as API key and HTTP authentication.
+ * It provides conversion to the corresponding SecurityScheme.Type enum.
+ */
 enum class Type(
     private val value: String,
 ) {
     APIKEY("apikey"),
     HTTP("http"),
     ;
 
+    /**
+     * Returns the string representation of the security type.
+     *
+     * @return String value of the security type
+     */
     override fun toString() = value
 
+    /**
+     * Converts this Type enum to the corresponding SecurityScheme.Type enum.
+     *
+     * This method converts the string value of this enum to uppercase and
+     * uses it to find the corresponding value in the SecurityScheme.Type enum.
+     *
+     * @return The corresponding SecurityScheme.Type enum value
+     */
     fun toEnum() = enumValueOf<SecurityScheme.Type>(value.uppercase(Locale.getDefault()))
 }

src/main/kotlin/io/opengood/autoconfig/openapidocs/property/ContactProperty.kt

@@ -1,5 +1,11 @@
 package io.opengood.autoconfig.openapidocs.property
 
+/**
+ * Configuration properties for contact information in OpenAPI documentation.
+ *
+ * This class defines the properties for contact information that will be displayed
+ * in the OpenAPI documentation, including name, URL, and email address.
+ */
 data class ContactProperty(
     val name: String = "",
     val url: String = "",

src/main/kotlin/io/opengood/autoconfig/openapidocs/property/LicenseProperty.kt

@@ -1,5 +1,11 @@
 package io.opengood.autoconfig.openapidocs.property
 
+/**
+ * Configuration properties for license information in OpenAPI documentation.
+ *
+ * This class defines the properties for license information that will be displayed
+ * in the OpenAPI documentation, including license name and URL.
+ */
 data class LicenseProperty(
     val name: String = "",
     val url: String = "",

src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ClientProperty.kt

@@ -1,5 +1,11 @@
 package io.opengood.autoconfig.openapidocs.property
 
+/**
+ * Configuration properties for OAuth2 client settings in OpenAPI documentation.
+ *
+ * This class defines the properties for OAuth2 client settings that will be used
+ * in the OpenAPI documentation, including the scopes that the client can request.
+ */
 data class Oauth2ClientProperty(
     val scopes: Map<String, String> = HashMap(),
 )

src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2Property.kt

@@ -2,6 +2,13 @@ package io.opengood.autoconfig.openapidocs.property
 
 import io.opengood.autoconfig.openapidocs.enumeration.Oauth2GrantType
 
+/**
+ * Configuration properties for OAuth2 settings in OpenAPI documentation.
+ *
+ * This class defines the properties for OAuth2 settings that will be used
+ * in the OpenAPI documentation, including grant type, resource configuration,
+ * client configuration, and token URI.
+ */
 data class Oauth2Property(
     val grantType: Oauth2GrantType = Oauth2GrantType.AUTHORIZATION_CODE,
     val resource: Oauth2ResourceProperty = Oauth2ResourceProperty(),