From 533d6949ee815c6adf04dc23952e616d17696dbc Mon Sep 17 00:00:00 2001 From: Chris Jaehnen Date: Sat, 7 Jun 2025 17:56:36 -0400 Subject: [PATCH 1/2] Add comments to production code --- .../autoconfig/openapidocs/Functions.kt | 10 ++++++++++ .../OpenApiDocsAutoConfiguration.kt | 16 +++++++++++++++ .../openapidocs/enumeration/BearerFormat.kt | 11 ++++++++++ .../enumeration/Oauth2GrantType.kt | 11 ++++++++++ .../openapidocs/enumeration/Scheme.kt | 11 ++++++++++ .../openapidocs/enumeration/Type.kt | 20 +++++++++++++++++++ .../openapidocs/property/ContactProperty.kt | 6 ++++++ .../openapidocs/property/LicenseProperty.kt | 6 ++++++ .../property/Oauth2ClientProperty.kt | 6 ++++++ .../openapidocs/property/Oauth2Property.kt | 7 +++++++ .../property/Oauth2ResourceProperty.kt | 6 ++++++ .../property/OpenApiDocsProperties.kt | 7 +++++++ .../openapidocs/property/SecurityProperty.kt | 7 +++++++ 13 files changed, 124 insertions(+) diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/Functions.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/Functions.kt index 8501d76..1173706 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/Functions.kt +++ b/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): Paths { val paths = Paths() list.forEach { paths.addPathItem(it, PathItem().get(Operation())) } diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt index 13ba192..b7f14f3 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt +++ b/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") diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/BearerFormat.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/BearerFormat.kt index d9756d4..4bc3348 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/BearerFormat.kt +++ b/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 } diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Oauth2GrantType.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Oauth2GrantType.kt index a6933d0..8b7e27a 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Oauth2GrantType.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Oauth2GrantType.kt @@ -1,5 +1,11 @@ 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, ) { @@ -7,5 +13,10 @@ enum class Oauth2GrantType( CLIENT_CREDENTIALS("clientCredentials"), ; + /** + * Returns the string representation of the OAuth2 grant type. + * + * @return String value of the OAuth2 grant type + */ override fun toString() = value } diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Scheme.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Scheme.kt index c187292..fbef804 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Scheme.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Scheme.kt @@ -1,5 +1,11 @@ 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, ) { @@ -7,5 +13,10 @@ enum class Scheme( BEARER("bearer"), ; + /** + * Returns the string representation of the security scheme. + * + * @return String value of the security scheme + */ override fun toString() = value } diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Type.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Type.kt index 13d6a9f..0c0df8d 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Type.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/enumeration/Type.kt @@ -3,6 +3,13 @@ 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, ) { @@ -10,7 +17,20 @@ enum class Type( 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(value.uppercase(Locale.getDefault())) } diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/ContactProperty.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/ContactProperty.kt index 4ffadee..5a2c102 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/ContactProperty.kt +++ b/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 = "", diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/LicenseProperty.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/LicenseProperty.kt index 0e83bc8..288278a 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/LicenseProperty.kt +++ b/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 = "", diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ClientProperty.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ClientProperty.kt index 39c846e..e3dccfd 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ClientProperty.kt +++ b/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 = HashMap(), ) diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2Property.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2Property.kt index 824df00..75abaad 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2Property.kt +++ b/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(), diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ResourceProperty.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ResourceProperty.kt index bd8a268..9dc0fa7 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ResourceProperty.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/Oauth2ResourceProperty.kt @@ -1,5 +1,11 @@ package io.opengood.autoconfig.openapidocs.property +/** + * Configuration properties for OAuth2 resource settings in OpenAPI documentation. + * + * This class defines the properties for OAuth2 resource settings that will be used + * in the OpenAPI documentation, including the authorization server URI. + */ data class Oauth2ResourceProperty( val authorizationServerUri: String = DEFAULT_AUTH_URI, ) { diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/OpenApiDocsProperties.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/OpenApiDocsProperties.kt index d8a5b42..ec60cf0 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/OpenApiDocsProperties.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/OpenApiDocsProperties.kt @@ -2,6 +2,13 @@ package io.opengood.autoconfig.openapidocs.property import org.springframework.boot.context.properties.ConfigurationProperties +/** + * Configuration properties for OpenAPI documentation. + * + * This class defines the configuration properties for OpenAPI documentation with the prefix "openapi-docs". + * It includes properties for enabling/disabling the documentation, API paths, metadata (title, description, etc.), + * contact information, license information, and security settings. + */ @ConfigurationProperties(prefix = "openapi-docs") data class OpenApiDocsProperties( val enabled: Boolean = true, diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/SecurityProperty.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/SecurityProperty.kt index 648c215..c9008d6 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/SecurityProperty.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/property/SecurityProperty.kt @@ -4,6 +4,13 @@ import io.opengood.autoconfig.openapidocs.enumeration.BearerFormat import io.opengood.autoconfig.openapidocs.enumeration.Scheme import io.opengood.autoconfig.openapidocs.enumeration.Type +/** + * Configuration properties for security settings in OpenAPI documentation. + * + * This class defines the properties for security settings that will be used + * in the OpenAPI documentation, including whether security is enabled, security name, + * description, scheme type, bearer format, and OAuth2 configuration. + */ data class SecurityProperty( val enabled: Boolean = true, val name: String = DEFAULT_SECURITY_NAME, From c40cfdc17ceb8db45243a996579fd6cb936b7444 Mon Sep 17 00:00:00 2001 From: Chris Jaehnen Date: Sat, 7 Jun 2025 18:00:18 -0400 Subject: [PATCH 2/2] Fix lint issues --- .../autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt b/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt index b7f14f3..e6e2726 100644 --- a/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt +++ b/src/main/kotlin/io/opengood/autoconfig/openapidocs/OpenApiDocsAutoConfiguration.kt @@ -16,7 +16,7 @@ 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".